On Thu, 4 Jul 2024 22:32:19 GMT, Archie Cobbs <aco...@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
