On Tue, 12 Jan 2021 05:55:07 GMT, liach <github.com+7806504+li...@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>.@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
