RFR: JDK-8202947: Fix minor issues with taglets

[K S]

Hi Jon,

The changes looks good, very nice cleanups.

Couple of minor comments and clarifications:

BaseConfiguration.java
I am assuming tokenize will not return a null.

+            switch (tokens.size()) {


SimpleTaglet.java

+                case 's':  case 'S':        // super-packages, anyone?

:)

+    private final LinkedHashMap<String,Taglet> allTaglets;

space after ,

 return b ? s : s.replaceAll(".", "."); // replace all with "."

I had to a double take the first argument is a regex, but the comment
helped.

Thanks

Kumar Srinivasan



On Mon, May 21, 2018 at 11:18 AM, Jonathan Gibbons <
jonathan.gibbons at oracle.com> wrote:

> 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.ja
>> vadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/
>> taglets/TagletManager.java.sdiff.html
>> [4] http://cr.openjdk.java.net/~jjg/8202947/webrev.00/src/jdk.ja
>> vadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/
>> taglets/BaseTaglet.java.sdiff.html
>>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180522/642b9a16/attachment.html>