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

Thu Dec 1 19:59:29 UTC 2022

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<number>"  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 <jjg at 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
>
>