RFR: JDK-8202947: Fix minor issues with taglets

[Jonathan Gibbons]

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