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

[Jonathan Gibbons]

Joe,

Thanks. Suggestions noted; will address them and push.

-- Jon


On 5/20/19 5:38 PM, Joe Darcy wrote:
>
> 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
>>>>
>>>>
>>>>
>>>
>>