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

Thu Dec 1 21:19:40 UTC 2022

On 11/28/22 3:27 PM, Phil Race wrote:
> 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
> src/java.desktop/share/classes/java/awt/package-info.java line 58:
>
>> 56:  *     <li><a href="doc-files/Modality.html">The AWT Modality</a>
>> 57:  *     <li><a href="{@docRoot}/../specs/AWT_Native_Interface.html">
>> 58:  *                  The Java AWT Native Interface (JAWT)</a>
> Why only 1 of these 3 ?

Only one is a link outside of the overall api/ documentation hierarchy 
(i.e. the one whose URL starts with {@docRoot}/../specs/), which is the 
focus of the `@spec` tag.  The other two links (only one shown in your 
email) both point to documentation within the same package.

>
> src/java.desktop/share/classes/java/awt/package-info.java line 62:
>
>> 60:  *
>> 61:  * @spec AWT_Native_Interface.html The Java AWT Native Interface Specification and Guide
>> 62:  * @since 1.0
> I wonder if links to html we include in the javadoc should be really treated in the same manner as referecnes to externally defined specifactions ?
> But I also wonder why only the native_interface spec was added and not the other two ?

The patch is generated by running a tool that detects existing links to 
either the sibling `specs` directory or to well-known hosts that provide 
specifications used by JDK.  It would be a feature-enhancement of the 
`@spec` tag to also accept "stand-alone" HTML files within the `api/` 
hierarchy of pages.

>
> src/java.desktop/share/classes/javax/imageio/plugins/tiff/BaselineTIFFTagSet.java line 226:
>
>> 224:      * @spec https://www.ietf.org/rfc/rfc1951.html RFC 1951: DEFLATE Compressed Data Format Specification version 1.3
>> 225:      * @see #TAG_COMPRESSION
>> 226:      * @see <a href="https://tools.ietf.org/html/rfc1951">DEFLATE specification</a>
> Does having @spec and @see mean we have two clickable links to the same place adjacent to each other ?

At this time yes, although the tooling does currently allow `@see` tags 
to be removed if the URL _and title_ match that used for the `@spec` 
tag.    Not all `@see` tags to a spec should be removed, since some may 
point to places within a spec, perhaps using a `#fragment` identifier, 
or to a sub-page within a multi-page spec.  It is my expectation that we 
may way to do a manual pass over the doc comments to examine places 
where there may be duplication, such that the `@see` tag can be updated 
and/ore removed.  That manual pass might also include updating to more 
normative URLs ... see the separate email discussion in the PR comments 
about changing `ietf.org` to `rfc-editor.org`.    Any such manual work 
would need to be done in conjunction with the relevant component teams.

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