Re: RFR: 8296546: Add @spec tags to API
On Thu, 10 Nov 2022 16:33:09 GMT, AJ1062910 wrote: > did you changed 420 files ? I ran a custom utility that edited these files, yes. - PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: 8296546: Add @spec tags to API
On Thu, 10 Nov 2022 01:10:13 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. 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. - PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: 8296546: Add @spec tags to API
On Thu, 10 Nov 2022 01:10:13 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. src/jdk.jdi/share/classes/com/sun/jdi/connect/spi/Connection.java line 105: > 103: * If the length of the packet (as indictaed by the first > 104: * 4 bytes) is less than 11 bytes, or an I/O error occurs. > 105: * @spec jdwp/jdwp-spec.html Java Debug Wire Protocol http://cr.openjdk.java.net/~jjg/8296546/api.00/jdk.jdi/com/sun/jdi/connect/spi/Connection.html#readPacket() Within this javadoc page the jdwp-spec.html references are titled "JDWP Specification", but these `@spec` references are titled "Java Debug Wire Protocol". I suggest making them more consistent. There is one more case below and this same issue also applies to TransportService.java. Perhaps the title in jdwp-spec.html should be updated. I think "Java Debug Wire Protocol (JDWP) Specification" would be good. src/jdk.jdi/share/classes/com/sun/jdi/connect/spi/TransportService.java line 79: > 77: * target VM. > 78: * > 79: * @spec jdwp/jdwp-spec.html Java Debug Wire Protocol See above comment for Connection.java. src/jdk.jdi/share/classes/module-info.java line 107: > 105: * > 106: * > 107: * @spec jpda/jpda.html Java Platform Debugger Architecture http://cr.openjdk.java.net/~jjg/8296546/api.00/jdk.jdi/module-summary.html `@spec` and `@see` sections end up one right after the other with the same content, except the `@see` section has the preferred hyperlink title. Suggest you remove the `@see` section and also update `@spec` hyperlink title to include "(JPDA)", or update the actual title in the jpda.html doc so it includes "(JPDA)" in it and then rerun your tool. src/jdk.jdwp.agent/share/classes/module-info.java line 30: > 28: * > 29: * @spec jdwp/jdwp-spec.html Java Debug Wire Protocol > 30: * @spec jdwp/jdwp-transport.html Java Debug Wire Protocol Transport > Interface (jdwpTransport) http://cr.openjdk.java.net/~jjg/8296546/api.00/jdk.jdwp.agent/module-summary.html The end result here is not very clean. You have the same two specs being referred to just a few lines apart, and the hyperlink titles are not even close to be the same, even though the links are the same. Maybe the "@see" section should be removed. - PR: https://git.openjdk.org/jdk/pull/11
Re: RFR: 8296546: Add @spec tags to API
On Thu, 10 Nov 2022 21:56:26 GMT, Jonathan Gibbons wrote: > On the same text but linking to different RFCs: that's tantamount to a bug > somewhere. The spec for `@spec` dictates that the URLs and titles should be > in 1-1 correspondence, and this is supposed to be enforced in the docket. In > other words, specs should have unique titles, and any title should only be > used for one spec. It's not uncommon for a newer version of a RFC to change its number but keep its title. I see that the links in the class level API documentation both have the RFC number in their link text. Somehow that was stripped by your tool - possibly because it tried to extract some meta information from the linked page itself? - PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: 8296546: Add @spec tags to API
On Thu, 10 Nov 2022 01:10:13 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.
Hi Jon,
I only looked at the jar specific updates but there is some duplication
leftovers.
It would probably be easier for the reviewers and for you if the PR could be
broken out by areas into separate PRs
src/java.base/share/classes/java/util/jar/Attributes.java line 58:
> 56: * order that keys were inserted into the map, as with {@link
> LinkedHashMap}.
> 57: *
> 58: * @spec jar/jar.html JAR File Specification
Line 52 should be removed
src/java.base/share/classes/java/util/jar/Attributes.java line 450:
> 448: * JAR File
> Specification
> 449: * for more information about valid attribute names and values.
> 450: * @spec jar/jar.html JAR File Specification
Line 448 should be removed
src/java.base/share/classes/java/util/jar/Manifest.java line 47:
> 45: * Manifest format specification.
> 46: *
> 47: * @spec jar/jar.html JAR File Specification
Line 44 should be removed
src/java.base/share/classes/java/util/jar/package-info.java line 47:
> 45: *
> 46: *
> 47: * @spec jar/jar.html JAR File Specification
Line 43 should be removed
src/java.base/share/classes/java/util/zip/package-info.java line 75:
> 73: *
> 74: *
> 75: * @spec https://www.ietf.org/rfc/rfc1951.html DEFLATE Compressed Data
> Format Specification version 1.3
The above references should be removed as they duplicate the` @spec` tags
-
Changes requested by lancea (Reviewer).
PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: 8296546: Add @spec tags to API
On Fri, 11 Nov 2022 11:45:43 GMT, Lance Andersen wrote: > It would probably be easier for the reviewers and for you if the PR could be > broken out by areas into separate PRs Leaving out the non-public and non-exported classes would also reduce the PR size. - PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: 8296546: Add @spec tags to API [v2]
> 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: Prefix RFC titles with `RFC :` - Changes: - all: https://git.openjdk.org/jdk/pull/11073/files - new: https://git.openjdk.org/jdk/pull/11073/files/30ce235f..c29092d8 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk&pr=11073&range=01 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=11073&range=00-01 Stats: 325 lines in 165 files changed: 4 ins; 4 del; 317 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
Re: RFR: 8296546: Add @spec tags to API [v2]
On Tue, 22 Nov 2022 22:04:57 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 incrementally with one > additional commit since the last revision: > > Prefix RFC titles with `RFC :` Thanks for adding the RFC prefix to the RFC link. What is the purpose of editing non exported classes though, like those in the `sun.net` subpackages? - PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: 8296546: Add @spec tags to API [v2]
On Wed, 23 Nov 2022 12:43:16 GMT, Daniel Fuchs wrote: > Thanks for adding the RFC prefix to the RFC link. What is the purpose of > editing non exported classes though, like those in the `sun.net` subpackages? That was not intentional, and is a result of the scripted edit. I will look to revert those changes and/or change the tooling to ignore those packages. - PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: 8296546: Add @spec tags to API [v3]
> 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 - Changes: - all: https://git.openjdk.org/jdk/pull/11073/files - new: https://git.openjdk.org/jdk/pull/11073/files/c29092d8..3905ac83 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk&pr=11073&range=02 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=11073&range=01-02 Stats: 34 lines in 25 files changed: 0 ins; 34 del; 0 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
Re: RFR: 8296546: Add @spec tags to API [v3]
On Wed, 23 Nov 2022 18:57:03 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 incrementally with one
> additional commit since the last revision:
>
> Remove updates from unexported files
The java.base/net/, java.http/, java.naming/ changes look reasonable to me -
though like Alan I wonder if it wouldn't be better to have an inline `{@spec }`
tag - similar to `{@systemProperty }`, rather than repeating all the references
outside of the context where they were cited. This probably also calls for a
review of these references by maintainers of the various areas - as some of
them might need some updating - e.g. linking to `rfceditor` as was previously
suggested, and double checking whether all of them still make sense. Not
something to be conducted within this PR though.
-
PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: 8296546: Add @spec tags to API [v3]
On Wed, 23 Nov 2022 19:20:53 GMT, Daniel Fuchs wrote:
> The java.base/net/, java.http/, java.naming/ changes look reasonable to me -
> though like Alan I wonder if it wouldn't be better to have an inline `{@spec
> }` tag - similar to `{@systemProperty }`, rather than repeating all the
> references outside of the context where they were cited. This probably also
> calls for a review of these references by maintainers of the various areas -
> as some of them might need some updating - e.g. linking to `rfceditor` as was
> previously suggested, and double checking whether all of them still make
> sense. Not something to be conducted within this PR though.
Believe me, I tried *very* hard to design and use an inline `{@spec}` tag but
such a tag effectively needs a normative external file to indicate the root of
a multi-page spec, and the definitive title, since inline tags either do not or
are unlikely to contain such information.
The general history of this work is:
* version 1: bimodal tag with no external file -- the content of the summary
page was effectively rubbish
* version 2: bimodal tag with an external file -- in discussion with @jddarcy
and CSR, we decided that was too much of a non-standard maintenance load
* version 3: new tag, with no external file needed -- as you see here
-
PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: 8296546: Add @spec tags to API [v3]
On Wed, 23 Nov 2022 18:57:03 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 incrementally with one > additional commit since the last revision: > > Remove updates from unexported files src/java.xml/share/classes/javax/xml/XMLConstants.java line 35: > 33: * @spec https://www.w3.org/TR/REC-xml-names Namespaces in XML 1.0 (Third > Edition) > 34: * @spec https://www.w3.org/TR/xml-names11 Namespaces in XML 1.1 (Second > Edition) > 35: * @spec https://www.w3.org/TR/xmlschema-1 XML Schema Part 1: Structures > Second Edition Hi Jon, I would agree with what Alan said earlier that the @see ref can be dropped. This particular class (XMLConstants.java [1]) is a good example for that argument: in the resulting javadoc, 5 specs were listed in the "External Specifications" section, 6 in "See Also:", and then they were listed again for each field. That's a lot of duplicates. Adding to the confusion was that the @spec and @see were not always the same, e.g. @spec XML 1.0. points to the fifth edition while @see second. A minor comment is that the '@spec's were rendered in one line while the @see refs a list. I would see the later is easier to read. [1] http://cr.openjdk.java.net/~jjg/8296546/api.00/java.xml/javax/xml/XMLConstants.html - PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: 8296546: Add @spec tags to API [v3]
On Wed, 23 Nov 2022 18:57:03 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 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 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 http://www.w3.org/TR/xpath";>XML Path Language (XPath) > Version 1.0 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
Re: RFR: 8296546: Add @spec tags to API [v3]
On Wed, 23 Nov 2022 18:57:03 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 incrementally with one > additional commit since the last revision: > > Remove updates from unexported files src/java.se/share/classes/module-info.java line 39: > 37: * > 38: * @spec jdwp/jdwp-spec.html Java Debug Wire Protocol > 39: * @spec jni/index.html Java Native Interface Specification One thing that that bothers me a bit here is that the JNI and JDWP specs will be listed as "External Specifications" in the generated javadoc. This heading is appropriate for RFCs and other standards that we reference but seems misleading for specifications that are part of Java SE. Has this come up already? - PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: 8296546: Add @spec tags to API [v3]
On Wed, 23 Nov 2022 18:57:03 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 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: * The AWT Modality > 57: * > 58: * The Java AWT Native Interface (JAWT) Why only 1 of these 3 ? 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 ? 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 https://tools.ietf.org/html/rfc1951";>DEFLATE > specification Does having @spec and @see mean we have two clickable links to the same place adjacent to each other ? - PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: 8296546: Add @spec tags to API [v3]
We hear you Mike :-) I have logged https://bugs.openjdk.org/browse/JDK-8297755 to update the links in java.net / java.net.http API documentation. best regards, -- daniel On 29/11/2022 03:14, Michael StJohns wrote: Hi - I need to repeat again. Please avoid using www.ietf.org as the URL base for referencing RFCs. The appropriate location is www.rfc-editor.org and is going to be more stable in the long run than any reference to an RFC that runs through the IETF's website. These two websites have different purposes, and the structure of the IETF website has changed at least once recently and may change again relatively (~5 years) soon. The most general and correct form for referencing RFCs is "https://www.rfc-editor.org/info/rfc" That will get you to the front page with pointers to all of the current semi-canonical versions of the spec (e.g. text, pdf-a, html, and xml). Mike
Re: RFR: 8296546: Add @spec tags to API [v3]
Hi - I need to repeat again. Please avoid using www.ietf.org as the URL base for referencing RFCs. The appropriate location is www.rfc-editor.org and is going to be more stable in the long run than any reference to an RFC that runs through the IETF's website. These two websites have different purposes, and the structure of the IETF website has changed at least once recently and may change again relatively (~5 years) soon. The most general and correct form for referencing RFCs is "https://www.rfc-editor.org/info/rfc" That will get you to the front page with pointers to all of the current semi-canonical versions of the spec (e.g. text, pdf-a, html, and xml). Mike On 11/28/2022 6:27 PM, Phil Race wrote: On Wed, 23 Nov 2022 18:57:03 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 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: * The AWT Modality 57: * 58: * The Java AWT Native Interface (JAWT) Why only 1 of these 3 ? 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 ? 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 https://tools.ietf.org/html/rfc1951";>DEFLATE specification Does having @spec and @see mean we have two clickable links to the same place adjacent to each other ? - PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: 8296546: Add @spec tags to API [v3]
On Wed, 23 Nov 2022 23:04:36 GMT, Joe Wang wrote: >> Jonathan Gibbons has updated the pull request incrementally with one >> additional commit since the last revision: >> >> Remove updates from unexported files > > src/java.xml/share/classes/javax/xml/XMLConstants.java line 35: > >> 33: * @spec https://www.w3.org/TR/REC-xml-names Namespaces in XML 1.0 >> (Third Edition) >> 34: * @spec https://www.w3.org/TR/xml-names11 Namespaces in XML 1.1 (Second >> Edition) >> 35: * @spec https://www.w3.org/TR/xmlschema-1 XML Schema Part 1: Structures >> Second Edition > > Hi Jon, > > I would agree with what Alan said earlier that the @see ref can be dropped. > This particular class (XMLConstants.java [1]) is a good example for that > argument: in the resulting javadoc, 5 specs were listed in the "External > Specifications" section, 6 in "See Also:", and then they were listed again > for each field. That's a lot of duplicates. Adding to the confusion was that > the @spec and @see were not always the same, e.g. @spec XML 1.0. > points to the fifth edition while @see second. > > A minor comment is that the '@spec's were rendered in one line while the @see > refs a list. I would see the later is easier to read. > > [1] > http://cr.openjdk.java.net/~jjg/8296546/api.00/java.xml/javax/xml/XMLConstants.html The presentation of lists of `@spec` tags was fixed separately (JDK-8297802), and is incorporated into the latest docs that demo this work. The same algorithm is now used for both `@see` and `@spec` tags ... if the links are short and do not contain commas, they will be displayed as an inline list; otherwise, they will be displayed in a bulleted list. - PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: 8296546: Add @spec tags to API [v3]
Mike, Thank you for the additional info. In general, the intent of this patch is to leverage the existing links in the doc comments, but given that there is now an intent to update those links as well, I have incorporated the change into the latest update. -- Jon On 11/28/22 7:14 PM, Michael StJohns wrote: Hi - I need to repeat again. Please avoid using www.ietf.org as the URL base for referencing RFCs. The appropriate location is www.rfc-editor.org and is going to be more stable in the long run than any reference to an RFC that runs through the IETF's website. These two websites have different purposes, and the structure of the IETF website has changed at least once recently and may change again relatively (~5 years) soon. The most general and correct form for referencing RFCs is "https://www.rfc-editor.org/info/rfc" That will get you to the front page with pointers to all of the current semi-canonical versions of the spec (e.g. text, pdf-a, html, and xml). Mike On 11/28/2022 6:27 PM, Phil Race wrote: On Wed, 23 Nov 2022 18:57:03 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 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: * The AWT Modality 57: * 58: * The Java AWT Native Interface (JAWT) Why only 1 of these 3 ? 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 ? 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 href="https://tools.ietf.org/html/rfc1951";>DEFLATE specification Does having @spec and @see mean we have two clickable links to the same place adjacent to each other ? - PR: https://git.openjdk.org/j
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&pr=11073&range=03 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=11073&range=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
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 [v3]
On 11/28/22 3:27 PM, Phil Race wrote:
On Wed, 23 Nov 2022 18:57:03 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 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: * The AWT Modality
57: *
58: * The Java AWT Native Interface (JAWT)
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 https://tools.ietf.org/html/rfc1951";>DEFLATE
specification
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 t
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, 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";>RFC 929: > 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";>RFC 1122 > 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";>RFC 1323: > 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";>RFC 793: > Transmission Remove the @see src/java.base/share/classes/java/net/
