On Tue, 9 Jan 2024 19:08:11 GMT, Chris Plummer <[email protected]> wrote:
>> 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.
Okay, thanks! Reasonable.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/17311#discussion_r1446709471
