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

Reply via email to