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

List:       openjdk-serviceability-dev
Subject:    Withdrawn: 8296546: Add @spec tags to API
From:       duke <duke () openjdk ! org>
Date:       2023-01-27 18:43:34
Message-ID: Bmh8EC1Xp-UN0iY-YE8mDhTuf06aJtr4orDONeB7J8U=.6380dac7-c81f-45be-aee5-4a5a3e6e2a5e () github ! com
[Download RAW message or body]

On Thu, 10 Nov 2022 01:10:13 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.

This pull request has been closed without being integrated.

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

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


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