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

[Chen Liang]

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.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractExecutableMemberWriter.java line 1:

> 1: /*

Need a copyright year bump

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Signatures.java line 1:

> 1: /*

Need a copyright year bump

test/langtools/jdk/javadoc/doclet/testConstructorGenericParam/TestConstructorGenericParam.java line 36:

> 34: import javadoc.tester.JavadocTester;
> 35: 
> 36: public class TestConstructorGenericParam extends JavadocTester {

Can we consolidate this into `testTypeParams` as this is related to type parameter declarations not being rendered on constructors?

test/langtools/jdk/javadoc/doclet/testConstructorGenericParam/pkg1/A.java line 24:

> 22:  */
> 23: 
> 24: package pkg1;

Older tests have standalone files for testing. Newer ones can just benefit from text blocks to avoid copyright headers: https://github.com/openjdk/jdk/commit/3a00fc732a959300a558d5062e5486220ea75192#diff-755f60e23aa546180d236ea3588409fd87f80159136b8dc03c65160ed244cfd5R203

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

PR Review Comment: https://git.openjdk.org/jdk/pull/20044#discussion_r1666123001
PR Review Comment: https://git.openjdk.org/jdk/pull/20044#discussion_r1666122079
PR Review Comment: https://git.openjdk.org/jdk/pull/20044#discussion_r1666121425
PR Review Comment: https://git.openjdk.org/jdk/pull/20044#discussion_r1666121808