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

[Jonathan Gibbons]

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
>
>
>