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

[Chris Plummer]

On Tue, 9 Jan 2024 07:24:57 GMT, Serguei Spitsyn <sspitsyn 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/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.

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

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