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

[Serguei Spitsyn]

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

>> src/jdk.jdi/share/classes/com/sun/jdi/VirtualMachine.java line 681:
>> 
>>> 679:      * class prepare events by source name.
>>> 680:      *
>>> 681:      * @see ClassPrepareRequest#addSourceNameFilter
>> 
>> It is not clear why the link has been removed. There are some other similar places with links but others without links, so it is not clear how to achieve consistency here. Just want to understand your logic.
>
> `@see` doesn't require using `@link`. It is implied. The text ends up in the `See Also:` section of the javadoc. The `See Also:` is just a list of links.
> 
> You may also see something like the following:
> 
>      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only
>      * - see {@link VirtualMachine#canBeModified()}.
> 
> In this case this is not something that ends up in the `See Also:` section. The text is simply part of the `@throw` description, and there is nothing special about the word `see`. Thus the `@link` is needed.
> 
> For this particular case you are commenting on, it seemed more appropriate to put this in the `See Also:` section rather than inlined with the descriptive text since it did not seem to be an extension of the sentence that preceded it.

Okay, thanks! Reasonable.

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

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