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

[3] [4]

Reply via email to