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

[Alan Bateman]

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()}.

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.

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

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