This introduces support for a new `@spec` tag that can be used as either an
inline tag or as a block tag. It is used to identify references to external
specifications, in such a way that the references can be collected together on
a new summary page, called "Other Specifications", available from either the
static INDEX page or the interactive search box.
As an inline tag, the format is `{@spec url label}`, which is roughly
translated to `<a href="url">label</a>` in the generated docs.
As a block tag, the format is simply
@spec url label
which is handled in a manner analogous to
@see <a href="url">label</a>
The tag is notable for being the first standard/supported tag that can be used
as either an inline or block tag. (We have had support for bimodal
non-standard/custom tags for a while, such as `{@jls}` and `{@jvms}`.) To
support bimodal standard tags, some changes to `DocCommentParser` are
incorporated here.
This change is only the _support_ for the new tag; it does _not_ include any
changes to API docs to _use_ the new tag.
-------------
Commit messages:
- fix TestSpecTag.testEncodedURI
- fix tests
- remove support to workaround legacy @spec tag
- Merge remote-tracking branch 'upstream/master' into new-spec-tag
- fix trailing whitespace in test
- temporarily allow existing legacy usage `@spec JPMS` `@spec jsr-51`
- JDK-6251738: Want a top-level summary page that itemizes all spec documents
referenced from javadocs (OEM spec)
Changes: https://git.openjdk.java.net/jdk/pull/790/files
Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=790&range=00
Issue: https://bugs.openjdk.java.net/browse/JDK-6251738
Stats: 1376 lines in 42 files changed: 1345 ins; 12 del; 19 mod
Patch: https://git.openjdk.java.net/jdk/pull/790.diff
Fetch: git fetch https://git.openjdk.java.net/jdk pull/790/head:pull/790
PR: https://git.openjdk.java.net/jdk/pull/790
