RFR: docs/build: JDK-8224166: Create a taglet to better handle @jls and @jvms tags

[Jonathan Gibbons]

Here is the updated webrev with the comment changes.

Webrev: http://cr.openjdk.java.net/~jjg/8224166-jls-jvms/webrev.01/

-- Jon


On 05/20/2019 01:43 PM, Jonathan Gibbons wrote:
> Joe notes some unbalanced parentheses in the doc-comment for the new 
> JSpec taglet:
>
> I will change the doc comment to read:
>
> /**
>  * A base class for block tags to insert a link to an external copy of 
> JLS or JVMS.
>  * The tags can be used as follows:
>  * @jls section-number description, for example
>  * <p>
>  * @jls 3.4 Line Terminators
>  * <p>
>  * will produce the following html
>  * <p>
>  * {@code
>  * <dt>See <i>Java Language Specification</i>:
>  * <dd><a 
> href="https://docs.oracle.com/javase/specs/jls/se12/html/jls-3.html#jls-3.4">3.4 
> Line terminators</a>
>  * }
>  *
>  * The version of the spec must be set in the jspec.version system 
> property.
>  */
>
> This removes a couple of excess '}' characters, and replaces the 
> unmemorable @ with the equivalent and slightly more readable named 
> entity, @
>
> -- Jon
>
> On 05/20/2019 12:45 PM, Jonathan Gibbons wrote:
>> Please review a small change to add support for new taglets to handle 
>> the @jls and @jvms tags found in our API docs.
>>
>> Previously, these tags were just handled with simple javadoc 
>> command-line options to echo their contents.  Now, the section number 
>> is found in the contents, and a link to the standard location for the 
>> full appropriate online spec is generated.
>>
>> Note that the links anticipate the publication of the updated 
>> versions of these specs in the standard location, and will be 404 
>> until the versions are available, at GA time.  If you want to 
>> preview/play with the links, you can tweak the version number use in 
>> Docs.gmk, line 278. It defaults to the current 
>> $$(VERSION_SPECIFICATION), meaning that it will be updated 
>> automatically as we move forward to new versions.
>>
>> The code for handling @jls and @jvms is sufficiently similar that 
>> they are implemented as nested classes within a single common 
>> supertype.   Of note is that the taglets do support the use of 
>> {@code} within the text.
>>
>> ...
>>
>> Separately, you may have noticed some cleanup changesets to 
>> standardize the use of these tags. Although those changes are related 
>> to this work, it is _not_ a requirement that the standard form is 
>> used.  The section number is extracted in the taglet with a fairly 
>> tolerant regex.
>>
>> -- Jon
>>
>>
>> JBS: https://bugs.openjdk.java.net/browse/JDK-8224166
>> Webrev: http://cr.openjdk.java.net/~jjg/8224166-jls-jvms/webrev.00/
>> API: 
>> http://cr.openjdk.java.net/~jjg/8224166-jls-jvms/docs/api/index.html
>>
>>
>>
>