On 11/28/22 3:27 PM, Phil Race wrote:
On Wed, 23 Nov 2022 18:57:03 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 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: * <li><a href="doc-files/Modality.html">The AWT Modality</a>
57: * <li><a href="{@docRoot}/../specs/AWT_Native_Interface.html">
58: * The Java AWT Native Interface (JAWT)</a>
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 <a href="https://tools.ietf.org/html/rfc1951";>DEFLATE
specification</a>
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 the `@see` tag can be updated
and/ore removed. That manual pass might also include updating to more
normative URLs ... see the separate email discussion in the PR comments
about changing `ietf.org` to `rfc-editor.org`. Any such manual work
would need to be done in conjunction with the relevant component teams.
-------------
PR: https://git.openjdk.org/jdk/pull/11073
