[prev in list] [next in list] [prev in thread] [next in thread] 

List:       openjdk-serviceability-dev
Subject:    Re: RFR: 8296546: Add @spec tags to API [v3]
From:       Phil Race <prr () openjdk ! org>
Date:       2022-11-28 23:27:55
Message-ID: JtvVGemz10-N9otE53_d4qnDX55iqR82daQ2EAFXdTM=.983f7514-3c5b-40af-a60d-0210cfec43a4 () github ! com
[Download RAW message or body]

On Wed, 23 Nov 2022 18:57:03 GMT, Jonathan Gibbons <jjg@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 ?

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 <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 ?

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

PR: https://git.openjdk.org/jdk/pull/11073


[prev in list] [next in list] [prev in thread] [next in thread]