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
