RFR: 8259216: javadoc omits method receiver for any nested type annotation [v3]

[Hannes Wallnöfer]

On Tue, 12 Jan 2021 05:55:07 GMT, liach <github.com+7806504+liach at openjdk.org> wrote:

>> Fixes the bug where receiver type is omitted in generated Javadoc when the immediate receiver type is not annotated (but some other type within is).
>> 
>> In addition, fixed the bug where receiver type for constructor is not properly qualified (without a clickable link), i.e. `OuterClass.this` vs `this`.
>> 
>> Testing can is done with these two Java Files:
>> `Ape.java`
>> public class Ape<T> {
>> 	public void m0(@Cute("m0") Ape<T>this) {}
>> 	public void m1(@Cute("m1 outer")Ape<@Cute("m1 inner") T>this) {}
>> 	public void m2(Ape<@Cute("m2") T>this) {}
>> 	public void m3(Ape<T> this) {}
>> 	public class Bee<Q, R> {
>> 		public Bee(Ape<@Cute("parent ape's T") T> Ape.this) {}
>>                 public Bee(@Cute("top level") Ape<T> Ape.this, Void varArg) {}
>> 		public void f0(Ape<T>.Bee<Q, R> this) {}
>> 		public void f1(Ape<T>.Bee<@Cute("Bee Q f1") Q, R> this) {}
>> 		public void f2(Ape<T>. at Cute("Bee f2") Bee<Q, R> this) {}
>> 		public void f3(Ape<@Cute("Ape T f3") T>.Bee<Q, R> this, Ape<@Cute("A regular param's ape T") Throwable>.Bee<Integer, Long> anotherParam) {}
>> 	}
>> }
>> 
>> `Cute.java`
>> import java.lang.annotation.Documented;
>> import java.lang.annotation.ElementType;
>> import java.lang.annotation.Retention;
>> import java.lang.annotation.RetentionPolicy;
>> import java.lang.annotation.Target;
>> 
>> @Documented
>> @Target(ElementType.TYPE_USE)
>> @Retention(RetentionPolicy.RUNTIME)
>> public @interface Cute {
>> 	String value() default "";
>> }
>> 
>> 
>> Before the fix (tested in oracle jdk 15.0.1):
>>  - javadoc misses receiver for `Ape#m2()` `Bee#<init>()` `Bee#f1()` `Bee#f3(Bee)` in the method details section 
>>  - javadoc's receiver for `Bee#<init>(Void)` is unqualified; such unqualified receiver fails in `javac`
>> After the fix:
>>  - The 4 methods now have receivers in method details.
>>    - `Ape#m3` `Bee#f0` still don't have receivers documented as their receivers are not annotated
>>    - `Bee#f3(Bee)`'s receiver is not annotated due to a distinct bug
>>  - javadoc's receiver for `Bee#<init>(Void)` is now qualified as `Bee.this` (without a link on `Bee`)
>> 
>> (Note: receiver parameters are never included in the method summary section; they only present in method details sections)
>> 
>> Non goal:
>>  - Won't fix the bug that a nested type's parent's type parameters are not documented, such as in `Ape.Bee#f3` in this example
>
> liach has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains one commit:
> 
>   8259216: javadoc omits method receiver for any nested type annotation

Thanks for the contribution, this looks good in general.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java line 348:

> 346:                 // kind 1
> 347:                 if (super.visitDeclared(t, unused) || visit(t.getEnclosingType()))
> 348:                     return true;

By convention we always use braces in if-statements.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java line 340:

> 338:             @Override
> 339:             public Boolean visitArray(ArrayType t, Void unused) {
> 340:                 // kind 0

Just wondering: what does "kind n" refer to?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java line 331:

> 329:     }
> 330: 
> 331:     public boolean isRecursivelyAnnotated(TypeMirror e) {

I'm not sure this needs to be a new public  method in `Utils` since it is only used by `AbstractExcecutableMemberWriter`. It also seems to do more than is necessary for that use case (array, wildcard).

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

PR: https://git.openjdk.java.net/jdk/pull/1997