RFR: 8323213: Fix some javadoc broken links in ObjectReference, and other misc javadoc cleanups

[Alan Bateman]

On Tue, 9 Jan 2024 19:09:33 GMT, Chris Plummer <cjplummer at openjdk.org> wrote:

>> src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java line 331:
>> 
>>> 329:      * <code>false</code> otherwise.
>>> 330:      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only
>>> 331:      * - see {@link VirtualMachine#canBeModified()}.
>> 
>> The alternative would be drop the "- see <link>" and add  `@see VirtualMachine#canBeModified()` on a new line so that it shows up in the "See also" list.
>
> There are a lot of places where we use `see` in this manner, because it applies specifically to the text that proceeds it. These 3 were different in that the space was missing.

I personally would not use this style, instead I would limit the `@throws` to just the simple sentence and then use `@see` for related methods, just as we do in the core APIs.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/17311#discussion_r1446541382