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