RFR: 6381729: Javadoc for generic constructor doesn't document type parameter

[Archie Cobbs]

On Thu, 4 Jul 2024 22:32:19 GMT, Archie Cobbs <acobbs at openjdk.org> wrote:

> The standard Javadoc doclet has a long-standing bug (since 2006, old enough to vote :) whereby constructor type parameters are simply omitted from the output. This results in confusing documentation that look like this:
> 
> public MyClass(T obj) - Description of this constructor...
> 
> with no explanation of what type `T` is.
> 
> The fix itself is straightforward (a one liner), but it requires a bit of prerequisite refactoring:
> 
> 1. The method `Signatures.appendTypeParameters()` would throw an NPE if given a constructor, because the `returnType` is null. This is easy to work around with a simple null check.
> 
> 2. The code for generating the HTML for the type parameters was embedded in a method `AbstractMemberWriter.addModifiersAndType()` which assumed a normal method with a return type. In order to make this bit resuable for constructors too, it has been extracted out into a new method `AbstractExecutableMemberWriter.addTypeParameters()`.
> 
> 3. `ConstructorWriter` has an optimization in which constructor modifiers are omitted if all constructors are `public`, a common case. This optimization is disabled using a field named `foundNonPubConstructor`. A side effect of this optimization is that the constructor summary table has only two columns instead of three (the first being unnecessary). However, type parameters should appear in the same column as modifiers, so this logic was generalized to check for both (a) all constructors `public`, and (b) no constructors with type parameters. The field `foundNonPubConstructor` has been renamed to `showConstructorModifiers`; this clarifies `ClassUseWriter` using it for that purpose when generating the use index.
> 
> The above steps have been broken out into separate commits.

Hi @liach - thanks for the comments. They should be addressed in cd3b2236012c9de8ca9377f0b30e29af321f1490 except for:
> Newer ones can just benefit from text blocks

It seemed appropriate to stay consistent with the existing format of `testTypeParams`, so I kept it as a separate file. Let me know if his makes sense to you. Thanks.

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

PR Comment: https://git.openjdk.org/jdk/pull/20044#issuecomment-2211103053