On Thu, 1 Dec 2022 19:36:16 GMT, Jonathan Gibbons <j...@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
