webrev.01 contains a minor update to this review.
1. Dummy taglets are registered for @uses and @provides so that they
appear in the printed taglet table
2. The test is updated for the @uses, @provides, and the JavaFX tags.
Webrev: http://cr.openjdk.java.net/~jjg/8202947/webrev.01/
-- Jon
On 05/17/2018 11:04 AM, Jonathan Gibbons wrote:
Please review some changes to the doclet support for taglets.
The change was initially motivated by a desire to better understand
which tags were supported in which contexts, to fix some issues in the
doc comment specification [1]. That in turn led to some cleanup in
the code to better understand the handling of such information in the
code itself. Finally, after doing before/after checking on the Java SE
API docs to verify that no change had occurred in the generated docs,
a change -was- identified, fixing a previously unknown bug, which
caused incorrect/inappropriate version info to appear in the generated
docs for JDK 9 and 10.
The JBS issue for this work is [2], but any changes that would allow
tags to appear in more places (implying a potential spec change) have
been deferred for now. In addition, as well as the previously unknown
bug described above, another previously unknown bug has been
identified, in the handling of the -tag option. This will be
investigated separately, and additional tests provided.
In terms of this work, the primary file to review first is
TagletManager [3]. While it is mostly cleanup, there is a new method
to print out a dump of the taglet table, which can be activated by a
new hidden/undocumented option. Secondarily, BaseTaglet [4] has been
improved, to make it unnecessary for subtypes to override methods that
define where the tag(let) can be used: the functionality is replaced
by passing in a Set<Site> to the BaseTaglet constructor, where Site is
a new enum whose members indicate the different places where a
tag(let) may appear.
A minor change to SimpleTaglet allows a taglet to be disabled. This is
used by the -author, -version, -nosince options, and by the 'X'
character in the `locations` part of a `-tag` option. Because this
changes the way that @author and @version tags are handled, new tests
are added for those tags, that exercise the tag and the corresponding
option.
A new "golden file" test is added for the dump of the taglet table.
This is partly to ensure the continued operation of the code to dump
the taglet table, and partly to help detect any inadvertent changes to
the taglet table.
-- Jon
[1] https://docs.oracle.com/javase/9/docs/specs/doc-comment-spec.html
[2] http://cr.openjdk.java.net/~jjg/8202947/webrev.00/
[3]
http://cr.openjdk.java.net/~jjg/8202947/webrev.00/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java.sdiff.html
[4]
http://cr.openjdk.java.net/~jjg/8202947/webrev.00/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/BaseTaglet.java.sdiff.html
