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

[Jonathan Gibbons]

On Wed, 3 May 2023 20:51:15 GMT, Phil Race <prr at openjdk.org> wrote:

>> 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.

For the `rfc-editor.org` that's going to be hard, insofar as there are strong opinions (voiced in an earlier round of review) about using references to the old sites.

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

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