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

[Jonathan Gibbons]

On Tue, 7 Jun 2022 01:10:24 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> 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.
>
> Hm... Which kind of "Error" would be thrown for which "other type"? I don't think that this method is ever called with an element other than a constructor or method; look:
> 
>     public ThrowsTaglet() {
>         super(DocTree.Kind.THROWS, false, EnumSet.of(Location.CONSTRUCTOR, Location.METHOD));
>     }
> 
> It is called for constructors regularly, but as you might imagine, it has no effect other than waste of resources and, what is more important, loss of code clarity. There are multiple types of executable elements. It's both clarifying and reassuring to see an assertion that establishes our programming assumptions as to which of those types we expect there, early in the method.

I continue to think that `assert` is little better than a stylized comment, since they are typically not enabled.

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

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