RFR: 8287333: Clean up ParamTaglet and ThrowsTaglet [v6]

[Pavel Rappo]

On Tue, 7 Jun 2022 13:38:48 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ParamTaglet.java line 94:
>> 
>>> 92:                     ? ee.getTypeParameters()
>>> 93:                     : ee.getParameters();
>>> 94:             String target = ch.getParameterName((ParamTree) input.docTreeInfo.docTree());
>> 
>> I'm guessing that it is not practical to have DocTreeInfo be generic in the DocTree field.
>> 
>> An alternative coding style here is to pass in an argument for the expected return type, as in
>> 
>>     String target = ch.getParameterName(input.docTreeInfo.docTree(ParamTree.class));
>
> That relates to the plan of dealing with `Input.tagId` that we discussed (chronologically) earlier in this PR. Since it's second time we touch this area, here are some bits of that plan.
> 
> Rather than generify `DocTreeInfo` and, therefore `DocFinder.Input`, we could first note a few things about `Input`:
> 
>   * `tagId` and `docTreeInfo` are used only by `ParamTaglet` and `ThrowsTaglet`
>   * `ParamTaglet` and `ThrowsTaglet` use `tagId` and `docTreeInfo` as poor surrogates for more specific types:
>       * `tagId` should be `Integer` for `ParamTaglet` and `TypeMirror` for `ThrowsTaglet`
>       * `Input.docTreeInfo.docTree` should be of different subtypes of `DocTree` (as you note)
>   * `isTypeVariableParamTag` is used only by `ParamTaglet`
> 
> Similarly, we note this for `Output`: `tagList` is only used by `ThrowsTaglet`.
> 
> What does it tell us? Well, to me it sounds like `Input` and `Output` are nonspecific bags of values used by all inheritable tags. That needlessly clutters `DocFinder`, which does not use *any* of those fields.
> 
> To declutter `DocFinder` and isolate inheritable taglets from each other, a subclass of inheritable taglet should instead use its own subclasses of `Input` and `Output` to pass all the necessary inheritance information.
> 
> I started working on that in JDK 19, didn't have enough time to finish. I plan to continue working on that in JDK 20,  where the result will hopefully land.

The plan is to address that in JDK-8285488.

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

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