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

Jonathan Gibbons jjg at openjdk.org
Wed Nov 23 18:57:03 UTC 2022

> 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


  - all: https://git.openjdk.org/jdk/pull/11073/files
  - new: https://git.openjdk.org/jdk/pull/11073/files/c29092d8..3905ac83

 - 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

More information about the compiler-dev mailing list