RFR: JDK-8253733: Cleanup internal taglet API [v2]

[Pavel Rappo]

On Wed, 30 Sep 2020 17:11:19 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> This is a general cleanup of various classes related to the handling of tags and taglets in the standard doclet.
>> 
>> The initial motivation was to clean up static methods on `TagletWriter` that took a `TagletWriter` as a parameter.
>> These methods are converted into instance methods, and the call sites simplified as well.
>> Another area of cleanup is to make clear which methods are used for inline tags and which are used for block tags.
>> 
>> Some dead code is removed, and the doc comments are generally cleaned up as well.  More details are given in the JBS
>> issue.
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Address review feedback

Marked as reviewed by prappo (Reviewer).

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletWriter.java line 282:

> 280:             } catch (UnsupportedTagletOperationException e) {
> 281:                 // malformed taglet:
> 282:                 // claims to support block tags (see Taglet.isBlockTag) but does not provide the

This version does a better job of explaining your assumptions. Thanks.

(You don't need to address the below comment.)

I think this method could benefit from an assertion or an unconditional check that would guard against calling this
method with a taglet list containing a non-block taglet. That is, a taglet `t` such that `t.isBlockTag() == false`.

This is a bit different from `TagletWriter#getInlineTagOutput` where the check is built into the method;
`TagletWriter#getBlockTagOutput` relies on a caller to pass the correct list.

-------------

PR: https://git.openjdk.java.net/jdk/pull/406