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

Fri Dec 2 12:15:23 UTC 2022

On Thu, 1 Dec 2022 19:36:16 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 with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains five additional commits since the last revision:
> 
>  - Change ietf.org URLs to use rfc-editor.org
>  - Merge remote-tracking branch 'upstream/master' into 8296546.add-spec-tags
>  - Remove updates from unexported files
>  - Prefix RFC titles with `RFC NNNN:`
>  - JDK-8296547: Add @spec tags to API

I have reviewed again the java.net, java.net.http, jdk.httpserver, java.naming, and javax.management changes - and I spotted a few places where the `@spec` duplicates an `@see` (noted below). I believe the duplicated `@see` should be removed now.

src/java.base/share/classes/java/net/StandardSocketOptions.java line 62:

> 60:      * @spec https://www.rfc-editor.org/info/rfc919 RFC 919: Broadcasting Internet Datagrams
> 61:      * @see <a href="http://www.ietf.org/rfc/rfc919.txt">RFC 929:
> 62:      * Broadcasting Internet Datagrams</a>

This `@see` line should now be removed since it's referencing the exact same document.

src/java.base/share/classes/java/net/StandardSocketOptions.java line 83:

> 81:      * @spec https://www.rfc-editor.org/info/rfc1122 RFC 1122: Requirements for Internet Hosts - Communication Layers
> 82:      * @see <a href="http://www.ietf.org/rfc/rfc1122.txt">RFC 1122
> 83:      * Requirements for Internet Hosts -- Communication Layers</a>

Same remark here: please remove the `@see`

src/java.base/share/classes/java/net/StandardSocketOptions.java line 154:

> 152:      * @spec https://www.rfc-editor.org/info/rfc1323 RFC 1323: TCP Extensions for High Performance
> 153:      * @see <a href="http://www.ietf.org/rfc/rfc1323.txt">RFC 1323: TCP
> 154:      * Extensions for High Performance</a>

Remove the `@see`

src/java.base/share/classes/java/net/StandardSocketOptions.java line 186:

> 184:      *
> 185:      * @spec https://www.rfc-editor.org/info/rfc793 RFC 793: Transmission Control Protocol
> 186:      * @see <a href="http://www.ietf.org/rfc/rfc793.txt">RFC 793: Transmission

Remove the @see

src/java.base/share/classes/java/net/StandardSocketOptions.java line 377:

> 375:      * @spec https://www.rfc-editor.org/info/rfc1122 RFC 1122: Requirements for Internet Hosts - Communication Layers
> 376:      * @see <a href="http://www.ietf.org/rfc/rfc1122.txt">RFC 1122:
> 377:      * Requirements for Internet Hosts -- Communication Layers</a>

Remove the @see

src/java.management/share/classes/javax/management/remote/JMXServiceURL.java line 122:

> 120:  * @see <a
> 121:  * href="http://www.ietf.org/rfc/rfc2609.txt">RFC 2609,
> 122:  * "Service Templates and <code>Service:</code> Schemes"</a>

The two `@see` should now be removed

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

Changes requested by dfuchs (Reviewer).

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