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

[Jonathan Gibbons]

On Wed, 30 Sep 2020 17:51:01 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Address review feedback
>
> 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.

Interesting question, worth considering ...

This is an internal API, so is only called from internal sites, with one of two lists supplied by the TagletManager:
standard block tags, or serial form tags (the latter is why the list comes in as an argument and is not provided
internally, as for inline tags.)

But given the list comes in as an argument, that suggests a reasonable update is to verify that all items in the
argument list are block tags, and to throw ILA if any are not.

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

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