RFR: JDK-8202947: Fix minor issues with taglets

[Jonathan Gibbons]

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