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
