RFR: JDK-8253733: Cleanup internal taglet API

[Jonathan Gibbons]

On Wed, 30 Sep 2020 10:24:01 GMT, Pavel Rappo <prappo 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.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SimpleTaglet.java line 182:
> 
>> 180:     @Override
>> 181:     public Content getInlineTagOutput(Element element, DocTree tag, TagletWriter writer) {
>> 182:         return null;
> 
> I know that the corresponding `simpleTagOutput` method was deleted in this patch, but could you explain why this is a
> valid substitution?

A better implementation would be remove this method, and rely on the underlying default impl to throw an exception;
I'll change code to do that.  The reason is that `SimpleTag` is only used for block tags, and this method is is (now)
clearly for inline tags.

This sort of confusion in the original code was significant contributing factor in replacing the one name for two
overloaded methods with two separate names for the different usages.

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

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