On Tue, 11 Apr 2023 20:09:40 GMT, Jonathan Gibbons <j...@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
