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

[Pavel Rappo]

On Mon, 6 Jun 2022 20:50:05 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 33 commits:
>> 
>>  - Merge branch 'master' into 8287333
>>    
>>    This resolves a conflict in ParamTaglet.
>>  - Clean up if-branch
>>  - Remove upper-bounded wildcard
>>    
>>    This change simplifies code without any disadvantages:
>>    
>>      * Those `List<? extends XTree>` are read-only
>>      * An argument of the `List<XTree>` type can still be passed to a `List<? extends XTree>` parameter
>>  - Simplify inheritThrowsDocumentation
>>  - Reuse more specific variable
>>  - Merge branch 'master' into 8287333
>>  - Incremental update
>>    
>>    - Renames local variables and method parameters
>>    - Improves comments
>>    - Removes debug leftovers
>>  - Update top-level doc comment
>>  - Trivially re-order assignments
>>    
>>    ...for re-use
>>  - Reformat for clarity
>>    
>>    Now it's very clear that the "Throws:" section consists of three types of exceptions:
>>    
>>      1. documented
>>      2. inherited
>>      3. undocumented
>>  - ... and 23 more: https://git.openjdk.java.net/jdk/compare/ebc012ec...6bbe871b
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ThrowsTaglet.java line 90:
> 
>> 88:                 output.tagList.add(tag);
>> 89:             } else if (target != null && candidate != null &&
>> 90:                     utils.isTypeElement(candidate) && utils.isTypeElement(target) && // FIXME: can they be anything else other than type elements?
> 
> what about `TypeParameterElement`?

I deleted that FIXME in a later commit. Also, that particular if-branch is to be looked at closely in JDK-8287796.

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ThrowsTaglet.java line 219:
> 
>> 217:                             .map(t -> (ThrowsTree) t)
>> 218:                             .toList();
>> 219:                     ExecutableElement r = declaredExceptionTags.put(inheritedTags, (ExecutableElement) inheritedDoc.holder);
> 
> I do not understand the need for saving the result

That was removed in a later commit, 6d51f62a.

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ThrowsTaglet.java line 237:
> 
>> 235:         Utils utils = writer.configuration().utils;
>> 236:         Content result = writer.getOutputInstance();
>> 237:         for (TypeMirror declaredExceptionType : declaredExceptionTypes) {
> 
> Two comments may have been too many, but zero is too few.

Did you see the name of that private method? Looks pretty self-descriptive to me. I'm not sure why you think it needs any comment, but I can re-introduce it, if you wish so.

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

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