RFR: 8296546: Add @spec tags to API [v3]

[Joe Wang]

On Wed, 23 Nov 2022 18:57:03 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a "somewhat automated" change to insert `@spec` tags into doc comments, as appropriate, to leverage the recent new javadoc feature to generate a new page listing the references to all external specifications listed in the `@spec` tags.
>> 
>> "Somewhat automated" means that I wrote and used a temporary utility to scan doc comments looking for HTML links to selected sites, such as `ietf.org`, `unicode.org`, `w3.org`. These links may be in the main description of a doc comment, or in `@see` tags. For each link, the URL is examined, and "normalized", and inserted into the doc comment with a new `@spec` tag, giving the link and tile for the spec.
>> 
>> "Normalized" means...
>> * Use `https:` where possible (includes pretty much all cases)
>> * Use a single consistent host name for all URLs coming from the same spec site (i.e. don't use different aliases for the same site)
>> * Point to the root page of a multi-page spec
>> * Use a consistent form of the spec, preferring HTML over plain text where both are available (this mostly applies to IETF specs)
>> 
>> In addition, a "standard" title is determined for all specs,  determined either from the content of the (main) spec page or from site index pages.
>> 
>> The net effect is (or should be) that **all** the changes are to just **add** new `@spec` tags, based on the links found in each doc comment. There should be no other changes to the doc comments, or to the implementation of any classes and interfaces.
>> 
>> That being said, the utility I wrote does have additional abilities, to update the links that it finds (e.g. changing to use `https:` etc,) but those features are _not_ being used here, but could be used in followup PRs if component teams so desired. I did notice while working on this overall feature that many of our links do point to "outdated" pages, some with eye-catching notices declaring that the spec has been superseded. Determining how, when and where to update such links is beyond the scope of this PR.
>> 
>> Going forward, it is to be hoped that component teams will maintain the underlying links, and the URLs in `@spec` tags, such that if references to external specifications are updated, this will include updating the `@spec` tags.
>> 
>> To see the effect of all these new `@spec` tags, see http://cr.openjdk.java.net/~jjg/8296546/api.00/
>> 
>> In particular, see the new [External Specifications](http://cr.openjdk.java.net/~jjg/8296546/api.00/external-specs.html) page, which you can also find via the new link near the top of the [Index](http://cr.openjdk.java.net/~jjg/8296546/api.00/index-files/index-1.html) pages.
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Remove updates from unexported files

Specs for XSLT and XPath (many occurrences) need to point to specific version (e.g. 1.0) rather than the "cover page" (this is an issue in the original javadoc).

src/java.xml/share/classes/javax/xml/transform/OutputKeys.java line 35:

> 33:  *
> 34:  * @spec https://www.w3.org/TR/xslt xslt cover page - W3C
> 35:  * @see <a href="http://www.w3.org/TR/xslt#output">

The pages for XSLT and XPath at W3C are organized differently from the days when this javadoc was created. The "latest version" now points to the "cover page". Could you change the spec to the following? 
      https://www.w3.org/TR/1999/REC-xslt-19991116 XSL Transformations (XSLT) Version 1.0
      
The @spec points to the general spec while @see also a specific section (similar situation as other classes in the package), if we want to keep @see ref here, it would be: 
    https://www.w3.org/TR/1999/REC-xslt-19991116#output

src/java.xml/share/classes/javax/xml/xpath/XPath.java line 104:

> 102:  * @author  Norman Walsh
> 103:  * @author  Jeff Suttor
> 104:  * @see <a href="http://www.w3.org/TR/xpath">XML Path Language (XPath) Version 1.0</a>

Similar situation as XSLT above, the latest version now points to "cover page". For this javadoc then, it needs to be:
    https://www.w3.org/TR/1999/REC-xpath-19991116/ XML Path Language (XPath) Version 1.0
    
Unlike XSLT, the original @see ref also points to the spec generally (not a specific section), we could then drop it to keep just the @spec ref.

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

PR: https://git.openjdk.org/jdk/pull/11073