On Thu, 10 Nov 2022 01:10:13 GMT, Jonathan Gibbons <j...@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. ------------- PR: https://git.openjdk.org/jdk/pull/11073
