RFR: 8259216: javadoc omits method receiver for any nested type annotation
liach
github.com+7806504+liach at openjdk.java.net
Mon Jan 11 19:36:09 UTC 2021
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
-------------
Commit messages:
- 8259216: javadoc omits method receiver for any nested type annotation
Changes: https://git.openjdk.java.net/jdk/pull/1997/files
Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=1997&range=00
Issue: https://bugs.openjdk.java.net/browse/JDK-8259216
Stats: 75 lines in 2 files changed: 53 ins; 8 del; 14 mod
Patch: https://git.openjdk.java.net/jdk/pull/1997.diff
Fetch: git fetch https://git.openjdk.java.net/jdk pull/1997/head:pull/1997
PR: https://git.openjdk.java.net/jdk/pull/1997
More information about the javadoc-dev
mailing list