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