On Wed, 3 May 2023 20:51:15 GMT, Phil Race <p...@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