RFR: JDK-8296547: Add @spec tags to API
Michael StJohns
mstjohns at comcast.net
Thu Nov 10 13:35:20 UTC 2022
Daniel et al -
Please avoid using ietf.org as the cite location for RFCs
The preferred cite for RFCs is generally via
www.rfc-editor.org/info/rfc<number> - that will get you to the info
page, but with links to pdf, html, and a clean .txt.
Cf https://www.rfc-editor.org/info/rfc4180 - "Cite this RFC" -
> Shafranovich, Y., "Common Format and MIME Type for Comma-Separated Values (CSV) Files", RFC 4180, DOI 10.17487/RFC4180, October 2005,<https://www.rfc-editor.org/info/rfc4180>.
Note that the most stable cite might be the DOI cite, but the above is
going to be fairly useful for a long time to come.
Mike
On 11/10/2022 6:34 AM, Daniel Fuchs 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, seehttp://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.
> Hi Jon,
>
> When referencing an RFC, it might be good to keep the RFC number in the text link. For instance I see that java.net.URL now has this:
>
> http://cr.openjdk.java.net/~jjg/8296546/api.00/java.base/java/net/URL.html
>
> External Specifications
> [Format for Literal IPv6 Addresses in URL's](https://www.ietf.org/rfc/rfc2732.html), [Uniform Resource Identifier (URI): Generic Syntax](https://www.ietf.org/rfc/rfc3986.html), [Uniform Resource Identifiers (URI): Generic Syntax](https://www.ietf.org/rfc/rfc2396.html)
>
> You will see that two of the RFC links have the same text but link to different RFCs, which I am finding confusing.
> Also I do hope it's clear that if a specification is referenced it doesn't mean it's being implemented.
>
> -------------
>
> PR:https://git.openjdk.org/jdk/pull/11073
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/security-dev/attachments/20221110/3423e68e/attachment.htm>
More information about the security-dev
mailing list