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

[Chris Plummer]

On Tue, 9 Jan 2024 18:44:04 GMT, Alan Bateman <alanb 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.

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.

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

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