On Wed, 23 Nov 2022 19:20:53 GMT, Daniel Fuchs <dfu...@openjdk.org> wrote:
> The java.base/net/, java.http/, java.naming/ changes look reasonable to me -
> though like Alan I wonder if it wouldn't be better to have an inline `{@spec
> }` tag - similar to `{@systemProperty }`, rather than repeating all the
> references outside of the context where they were cited. This probably also
> calls for a review of these references by maintainers of the various areas -
> as some of them might need some updating - e.g. linking to `rfceditor` as was
> previously suggested, and double checking whether all of them still make
> sense. Not something to be conducted within this PR though.
Believe me, I tried *very* hard to design and use an inline `{@spec}` tag but
such a tag effectively needs a normative external file to indicate the root of
a multi-page spec, and the definitive title, since inline tags either do not or
are unlikely to contain such information.
The general history of this work is:
* version 1: bimodal tag with no external file -- the content of the summary
page was effectively rubbish
* version 2: bimodal tag with an external file -- in discussion with @jddarcy
and CSR, we decided that was too much of a non-standard maintenance load
* version 3: new tag, with no external file needed -- as you see here
-------------
PR: https://git.openjdk.org/jdk/pull/11073
