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

[Jonathan Gibbons]

On Sun, 5 Jun 2022 20:55:12 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> A cleanup to facilitate fixing bugs like JDK-6509045: `{@inheritDoc}` only copies one instance of the specified exception.
>
> 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 206:

> 204:             // Of these two, only methods inherit documentation.
> 205:             // Don't waste time on constructors.
> 206:             assert holder.getKind() == ElementKind.CONSTRUCTOR : holder.getKind();

This is weaker than the old code, which would throw an Error on other types.  `assert` may or may not be enabled.

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

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