RFR: 8296546: Add @spec tags to API [v3]

[Jonathan Gibbons]

On Wed, 23 Nov 2022 19:20:53 GMT, Daniel Fuchs <dfuchs at 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