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. This needs to be coordinated with @hns who is working on similar issues. He is currently OOTO, but will be back soon. ------------- PR Comment: https://git.openjdk.org/jdk/pull/20044#issuecomment-2218653503
