Re: RFR: 8296546: Add @spec tags to API [v4]
On Thu, 1 Dec 2022 19:36:16 GMT, Jonathan Gibbons 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 :` > - 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 http://www.ietf.org/rfc/rfc919.txt;>RFC929: > 62: * Broadcasting Internet Datagrams 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 http://www.ietf.org/rfc/rfc1122.txt;>RFC1122 > 83: * Requirements for Internet Hosts -- Communication Layers 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 http://www.ietf.org/rfc/rfc1323.txt;>RFC1323: > TCP > 154: * Extensions for High Performance 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 http://www.ietf.org/rfc/rfc793.txt;>RFC793: > Transmission Remove the @see
Re: RFR: 8296546: Add @spec tags to API [v4]
On Thu, 1 Dec 2022 19:37:28 GMT, Jonathan Gibbons wrote: >> src/java.base/share/classes/java/lang/Character.java line 172: >> >>> 170: * occur. For example, in a future release, synchronization may fail. >>> 171: * >>> 172: * @spec https://www.unicode.org/reports/tr27 Unicode 3.1.0 >> >> This should probably be removed, as the original link (explaining `U+n` >> notation) is broken. > > @naotoj The edits are driven by a script, using info about existing links in > the same doc comment. If you don't think this reference is appropriate, it > would be better to either remove the existing link (and I'll regenerate this > patch) or else this patch goes through and you fix up both the existing link > and the `@spec` tag afterwards. Either way is fine with me. I will fix it up if you choose the latter. - PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: 8296546: Add @spec tags to API [v4]
On Thu, 10 Nov 2022 23:51:19 GMT, Naoto Sato wrote: >> 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 :` >> - JDK-8296547: Add @spec tags to API > > src/java.base/share/classes/java/lang/Character.java line 172: > >> 170: * occur. For example, in a future release, synchronization may fail. >> 171: * >> 172: * @spec https://www.unicode.org/reports/tr27 Unicode 3.1.0 > > This should probably be removed, as the original link (explaining `U+n` > notation) is broken. @naotoj The edits are driven by a script, using info about existing links in the same doc comment. If you don't think this reference is appropriate, it would be better to either remove the existing link (and I'll regenerate this patch) or else this patch goes through and you fix up both the existing link and the `@spec` tag afterwards. - PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: 8296546: Add @spec tags to API [v4]
> 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 :` - JDK-8296547: Add @spec tags to API - Changes: - all: https://git.openjdk.org/jdk/pull/11073/files - new: https://git.openjdk.org/jdk/pull/11073/files/3905ac83..07882ffc Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=11073=03 - incr: https://webrevs.openjdk.org/?repo=jdk=11073=02-03 Stats: 83309 lines in 1834 files changed: 38491 ins; 27762 del; 17056 mod Patch: https://git.openjdk.org/jdk/pull/11073.diff Fetch: git fetch https://git.openjdk.org/jdk pull/11073/head:pull/11073 PR: https://git.openjdk.org/jdk/pull/11073
