RFR: JDK-8305593: Add @spec tags in java.desktop

[Phil Race]

On Tue, 11 Apr 2023 20:09:40 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/java.desktop/share/classes/java/awt/Desktop.java line 591:
>> 
>>> 589:      * subprocess
>>> 590:      * @spec https://www.rfc-editor.org/info/rfc2368
>>> 591:      *      RFC 2368: The mailto URL scheme
>> 
>> The javadoc above references ietf.org. This tag references rfc-editor.org. It seems odd to use two different URLs
>> in the same method specification for the same RFC. I would have thought the ietf one better to use .. although it should be updated to https
>
> This work is primarily about adding `@spec` tags, in a semi-automated fashion, using a custom utility that scans comments in the public API, looking for `href`s to "well-known" sites hosting external specifications.  While "mostly automated", I did manually cleanup the references by line-wrapping as appropriate.
> 
> It is out of scope at this time to cleanup up the underlying `href`s, although we should look at cleaning up those links later, identifying the latest/preferred URL for the appropriate version of the spec document, which may or may not be the latest overall version of the spec. (For example, the client docs reference HTML 3.2, and should not reference anything more recent.). This cleanup can be done later and needs to be done in conjunction with the relevant teams, and probably not as a semi-automated update.   Such cleanup should be somewhat easier once we have tagged the affected comments with the relevant `@spec` tags.
> 
> I note that once we have completed the addition of the `@spec` tags, we will, re-enable the new "External Specifications" page, which cross-references where each individual external specification is mentioned in the overall API documentation.

Sorry, but no matter how many times I try, it seems wrong to even for some short amount of time to have @spec point to one place and the javadoc point to another. They should always be consistent.
If it is out of  scope to update the javadoc, then the new spec tag should just match the existing javadoc.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/13360#discussion_r1184267504