RFR: 8296546: Add @spec tags to API

[Jonathan Gibbons]

On 11/10/22 8:18 PM, Chris Plummer wrote:
> On Thu, 10 Nov 2022 01:10:13 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.
> src/jdk.jdi/share/classes/com/sun/jdi/connect/spi/Connection.java line 105:
>
>> 103:      *          If the length of the packet (as indictaed by the first
>> 104:      *          4 bytes) is less than 11 bytes, or an I/O error occurs.
>> 105:      * @spec jdwp/jdwp-spec.html Java Debug Wire Protocol
> http://cr.openjdk.java.net/~jjg/8296546/api.00/jdk.jdi/com/sun/jdi/connect/spi/Connection.html#readPacket()
>
> Within this javadoc page the jdwp-spec.html references are titled "JDWP Specification", but these `@spec` references are titled "Java Debug Wire Protocol". I suggest making them more consistent. There is one more case below and this same issue also applies to TransportService.java. Perhaps the title in jdwp-spec.html should be updated. I think "Java Debug Wire Protocol (JDWP) Specification" would be good.
>
> src/jdk.jdi/share/classes/com/sun/jdi/connect/spi/TransportService.java line 79:
>
>> 77:  * target VM.
>> 78:  *
>> 79:  * @spec jdwp/jdwp-spec.html Java Debug Wire Protocol
> See above comment for Connection.java.
>
> src/jdk.jdi/share/classes/module-info.java line 107:
>
>> 105:  *
>> 106:  *
>> 107:  * @spec jpda/jpda.html Java Platform Debugger Architecture
> http://cr.openjdk.java.net/~jjg/8296546/api.00/jdk.jdi/module-summary.html
>
> `@spec` and `@see` sections end up one right after the other with the same content, except the `@see` section has the preferred hyperlink title. Suggest you remove the `@see` section and also update `@spec` hyperlink title to include "(JPDA)", or update the actual title in the jpda.html doc so it includes "(JPDA)" in it and then rerun your tool.
>
> src/jdk.jdwp.agent/share/classes/module-info.java line 30:
>
>> 28:  *
>> 29:  * @spec jdwp/jdwp-spec.html Java Debug Wire Protocol
>> 30:  * @spec jdwp/jdwp-transport.html Java Debug Wire Protocol Transport Interface (jdwpTransport)
> http://cr.openjdk.java.net/~jjg/8296546/api.00/jdk.jdwp.agent/module-summary.html
>
> The end result here is not very clean. You have the same two specs being referred to just a few lines apart, and the hyperlink titles are not even close to be the same, even though the links are the same. Maybe the "@see" section should be removed.


Chris,

The general problem is that we're starting from an inconsistent code base.

Like you, I believe we should strive for consistency, especially between 
the title of the document and the label used in any URLs that point 
directly at the document.

This patch is generated by tooling that understands specific families of 
specs, including sites like `ietf.org` and the sibling `specs` 
directory.  I can update the title used in any `@spec` tag for any 
document in the sibling specs directory, but it is out of scope for this 
work to change the title within any specific document. That would need 
to be done in separate Enhancements, preferably by the teams owning the 
relevant documents.

As for `@see` tags, the tooling currently has the ability to remove a 
`@see` tag if both the URL and title match, although I have not enabled 
that option in the work so far.   It might be reasonable to 
automatically remove the `@see` tag if just the URL matches, meaning it 
points to the same page, with no #fragment identifier.

-- Jon


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