RFR: JDK-6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec)
Hannes Wallnöfer
hannesw at openjdk.java.net
Wed Nov 4 15:53:59 UTC 2020
On Thu, 22 Oct 2020 02:40:44 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:
> 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.
It's very instructive to see a new tag introduced from scratch with all the accompanying infrastructure and tests. The changes looks good to me, but I need to stress than I'm not an expert on some of the affected areas such as the jdk.compiler parts.
-------------
Marked as reviewed by hannesw (Reviewer).
PR: https://git.openjdk.java.net/jdk/pull/790
More information about the compiler-dev
mailing list