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

[Jonathan Gibbons]

On Fri, 7 Apr 2023 01:35:58 GMT, Phil Race <prr at openjdk.org> wrote:

>> Please review a docs-only change to add `@spec` tags into `java.desktop` public API files
>
> 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.

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

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