RFR [15] JDK-8235926: Update @jls @jvms taglets to allow inline usage
Jonathan Gibbons
jonathan.gibbons at oracle.com
Fri Dec 13 21:21:21 UTC 2019
Please review a change to the JDK-specific taglet used to generate links
to the JLS and JVMS specifications. The change is to allow instances of
these tags to be used inline as well as in the series of block tags at
the end of a comment.
The change leverages the recent fix for javadoc itself, JDK-8235306,
which updates javadoc to allow taglets (in general) to opt-in to bimodal
use.
The generated HTML is either the `<dt>...<dd...>` pair as before, for
block-tag instances, or a simple `<a href...>...</a>` for the
newly-supported inline instances. It is intentional that the new text
for inline instances does /not/ include any prefix like "See: Java
Language Specification", since that is better handled in the surrounding
text.
This fix does not update any JDK docs to use inline instances; it is
just about permitting them.
The taglet is the build.tools package. Although it is executed in the
"interim javadoc tool" (i.e. latest sources on boot JDK) it is compiled
against the boot JDK. For this reason, a method which would normally be
marked `@Override` cannot be so marked until JDK 15 is the boot JDK.
This does not affect the use of the tag in the interim javadoc.
Build tools don't have automated tests. This code was manually tested
by temporarily editing some JDK API to use both the old form and the new
form. The generated file was visually inspected, and also confirmed to
have no warnings or errors reported by the standard `tidy` utility.
-- Jon
JBS: https://bugs.openjdk.java.net/browse/JDK-8235926
Webrev: http://cr.openjdk.java.net/~jjg/8235926/webrev.00/
More information about the build-dev
mailing list