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

[Joe Darcy]

Hi Jon,

Minor suggestions for the javadoc, but otherwise good to push: in

>    45  * The tags can be used as follows:
>    46  * @jls section-number description, for example
>    47  * <p>
I suggest having "* @jls section-number description" on its own 
line to emphasize this is a block tag rather than an inline tag. and for

>    50  * will produce the following html
>    51  * <p>
>    52  * {@code
>    53  * <dt>See <i>Java Language Specification</i>:
>    54  * <dd><a href="https://docs.oracle.com/javase/specs/jls/se12/html/jls-3.html#jls-3.4">3.4 Line terminators</a>
>    55  * }

change line 50 to state "will produce the following html for a docs 
build configured for Java SE 12."

Thanks,

-Joe

On 5/20/2019 4:51 PM, Jonathan Gibbons wrote:
> 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
>>>
>>>
>>>
>>
>