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

classic Classic list List threaded Threaded
15 messages Options
Reply | Threaded
Open this post in threaded view
|

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

liach
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

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

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
Reply | Threaded
Open this post in threaded view
|

Re: RFR: 8259216: javadoc omits method receiver for any nested type annotation

Dalibor Topic-6
On Fri, 8 Jan 2021 04:56:47 GMT, liach <[hidden email]> 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

Hi,
Please send an e-mail to [hidden email] so that I can mark your account as verified.

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

PR: https://git.openjdk.java.net/jdk/pull/1997
Reply | Threaded
Open this post in threaded view
|

Re: RFR: 8259216: javadoc omits method receiver for any nested type annotation

liach
On Fri, 8 Jan 2021 18:39:21 GMT, Dalibor Topic <[hidden email]> 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
>
> Hi,
> Please send an e-mail to [hidden email] so that I can mark your account as verified.

Done.

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

PR: https://git.openjdk.java.net/jdk/pull/1997
Reply | Threaded
Open this post in threaded view
|

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

liach
In reply to this post by liach
> 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

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

Changes: https://git.openjdk.java.net/jdk/pull/1997/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=1997&range=01
  Stats: 73 lines in 2 files changed: 53 ins; 8 del; 12 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
Reply | Threaded
Open this post in threaded view
|

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

liach
In reply to this post by liach
> 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

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

Changes: https://git.openjdk.java.net/jdk/pull/1997/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=1997&range=02
  Stats: 101 lines in 3 files changed: 69 ins; 6 del; 26 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
Reply | Threaded
Open this post in threaded view
|

Re: RFR: 8259216: javadoc omits method receiver for any nested type annotation

liach
In reply to this post by liach
On Fri, 8 Jan 2021 19:23:44 GMT, liach <[hidden email]> wrote:

>> Hi,
>> Please send an e-mail to [hidden email] so that I can mark your account as verified.
>
> Done.

A quick summary:
1. Receivers now are included if any part of their type hierarchy is annotated, such as on a type argument. Cannot test on nested classes due to [JDK-8259499](https://bugs.openjdk.java.net/browse/JDK-8259499). [a test case for 1](https://github.com/openjdk/jdk/pull/1997/files#diff-f0952a0ae5e2e84793298c953e1080ad55516d3096a3832c23ac4e8898d2230eR804-R808)
2. Now receiver's type annotations are concatenated to the receiver's type like type annotations on regular parameters, i.e. with a space than a no-break space. Tests have been updated to expect regular than no-break spaces.

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

PR: https://git.openjdk.java.net/jdk/pull/1997
Reply | Threaded
Open this post in threaded view
|

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

Hannes Wallnöfer
In reply to this post by liach
On Tue, 12 Jan 2021 05:55:07 GMT, liach <[hidden email]> 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
Reply | Threaded
Open this post in threaded view
|

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

liach
On Tue, 12 Jan 2021 12:09:48 GMT, Hannes Wallnöfer <[hidden email]> wrote:

>> 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
>
> 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?

It is the "type path kind" as defined in https://docs.oracle.com/javase/specs/jvms/se15/html/jvms-4.html#jvms-4.7.20.2-210

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

PR: https://git.openjdk.java.net/jdk/pull/1997
Reply | Threaded
Open this post in threaded view
|

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

liach
In reply to this post by liach
> 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

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

Changes: https://git.openjdk.java.net/jdk/pull/1997/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=1997&range=03
  Stats: 85 lines in 3 files changed: 50 ins; 6 del; 29 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
Reply | Threaded
Open this post in threaded view
|

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

liach
In reply to this post by Hannes Wallnöfer
On Tue, 12 Jan 2021 12:34:44 GMT, Hannes Wallnöfer <[hidden email]> wrote:

>> liach has updated the pull request with a new target base due to a merge or a rebase.
>
> 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).

Agreed. Moved this to a helper method like `addParameters` in `AbstractExcecutableMemberWriter`. Also changed test so the tests for `Generic2`'s doc group together.

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

PR: https://git.openjdk.java.net/jdk/pull/1997
Reply | Threaded
Open this post in threaded view
|

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

Hannes Wallnöfer
In reply to this post by liach
On Tue, 12 Jan 2021 15:41:06 GMT, liach <[hidden email]> 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

Looks good!  The only issue I found is a change in wording in a doc comment (see inline comment).

Please note that you can push an incremental commit to your branch so you don't have to force-push, this also makes it easier to review.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractExecutableMemberWriter.java line 175:

> 173:
> 174:     /**
> 175:      * Returns if a receiver type is annotated anywhere in its type for

Should read "Returns {@code true} if..."

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

PR: https://git.openjdk.java.net/jdk/pull/1997
Reply | Threaded
Open this post in threaded view
|

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

liach
In reply to this post by liach
> 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

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

Changes: https://git.openjdk.java.net/jdk/pull/1997/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=1997&range=04
  Stats: 84 lines in 3 files changed: 50 ins; 6 del; 28 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
Reply | Threaded
Open this post in threaded view
|

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

liach
In reply to this post by Hannes Wallnöfer
On Thu, 14 Jan 2021 12:32:42 GMT, Hannes Wallnöfer <[hidden email]> wrote:

>> liach has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractExecutableMemberWriter.java line 175:
>
>> 173:
>> 174:     /**
>> 175:      * Returns if a receiver type is annotated anywhere in its type for
>
> Should read "Returns {@code true} if..."

Done. Rebased to fix merge conflict as well.

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

PR: https://git.openjdk.java.net/jdk/pull/1997
Reply | Threaded
Open this post in threaded view
|

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

Hannes Wallnöfer
In reply to this post by liach
On Thu, 14 Jan 2021 13:43:17 GMT, liach <[hidden email]> 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

Looks good!

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

Marked as reviewed by hannesw (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/1997
Reply | Threaded
Open this post in threaded view
|

Integrated: 8259216: javadoc omits method receiver for any nested type annotation

liach
In reply to this post by liach
On Fri, 8 Jan 2021 04:56:47 GMT, liach <[hidden email]> 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

This pull request has now been integrated.

Changeset: eb7fa006
Author:    liach <[hidden email]>
Committer: Hannes Wallnöfer <[hidden email]>
URL:       https://git.openjdk.java.net/jdk/commit/eb7fa006
Stats:     84 lines in 3 files changed: 50 ins; 6 del; 28 mod

8259216: javadoc omits method receiver for any nested type annotation

Reviewed-by: hannesw

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

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