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

[Serguei Spitsyn]

On Mon, 8 Jan 2024 20:16:50 GMT, Chris Plummer <cjplummer at openjdk.org> wrote:

> Fix some broken links and other minor cleanups:
> 
>  There are a few broken links in the javadoc for ObjectReference.java. For example:
> 
> 
>      * Not all target VMs support this operation. See
>      * VirtualMachine#canGetMonitorInfo to determine if the
>      * operation is supported.
> 
> 
> Which should be:
> 
> 
>      * Not all target VMs support this operation. See
>      * {@link VirtualMachine#canGetMonitorInfo} to determine if the
>      * operation is supported.
> 
> 
> 
> The following does not need to include the link text:
> 
> `     * {@link VirtualMachine#canGetInstanceInfo() canGetInstanceInfo()}`
> 
> Instead just use:
> 
> `     * {@link VirtualMachine#canGetInstanceInfo()}`
> 
> 
> There are many places where we embed a "see" rather than use @see. The formatting convention is:
> 
> `     * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.`
> 
> However, there are a few places that are missing a space before the "see":
> 
> 
>      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only
>      * -see {@link VirtualMachine#canBeModified()}.

Looks good to me.

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.

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

Marked as reviewed by sspitsyn (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17311#pullrequestreview-1810539818
PR Review Comment: https://git.openjdk.org/jdk/pull/17311#discussion_r1445712962