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.

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

Commit messages:
 - JDK-8296547: Add @spec tags to API

Changes: https://git.openjdk.org/jdk/pull/11073/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=11073&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8296547
  Stats: 816 lines in 420 files changed: 816 ins; 0 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

Reply via email to