On Mon, 29 Jul 2024 19:14:40 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. > > Thanks very much for the reviews. On a side note, @archiecobbs you can add your openjdk email acobbs at openjdk to your github account for github to correctly attribute your commits. (this address delegates your jbs email) ------------- PR Comment: https://git.openjdk.org/jdk/pull/20044#issuecomment-2256724979
