8259216: javadoc omits method receiver for any nested type annotation #1997

liach · 2021-01-08T04:56:47Z

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

Progress

Change must not contain extraneous whitespace
Commit message must refer to an issue
Change must be properly reviewed

Issue

JDK-8259216: javadoc omits method receiver for any nested type annotation

Reviewers

Hannes Wallnöfer (@hns - Reviewer)

Download

$ git fetch https://git.openjdk.java.net/jdk pull/1997/head:pull/1997
$ git checkout pull/1997

bridgekeeper · 2021-01-08T04:57:33Z

Hi @liach, welcome to this OpenJDK project and thanks for contributing!

We do not recognize you as Contributor and need to ensure you have signed the Oracle Contributor Agreement (OCA). If you have not signed the OCA, please follow the instructions. Please fill in your GitHub username in the "Username" field of the application. Once you have signed the OCA, please let us know by writing /signed in a comment in this pull request.

If you already are an OpenJDK Author, Committer or Reviewer, please click here to open a new issue so that we can record that fact. Please use "Add GitHub user liach" as summary for the issue.

If you are contributing this work on behalf of your employer and your employer has signed the OCA, please let us know by writing /covered in a comment in this pull request.

openjdk · 2021-01-08T04:58:33Z

@liach The following label will be automatically applied to this pull request:

javadoc

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

liach · 2021-01-08T05:14:23Z

/signed

bridgekeeper · 2021-01-08T05:15:11Z

Thank you! Please allow for up to two weeks to process your OCA, although it is usually done within one to two business days. Also, please note that pull requests that are pending an OCA check will not usually be evaluated, so your patience is appreciated!

robilad · 2021-01-08T18:39:21Z

Hi,
Please send an e-mail to Dalibor.topic@oracle.com so that I can mark your account as verified.

liach · 2021-01-08T19:23:44Z

Done.

mlbridge · 2021-01-11T19:36:08Z

Webrevs

04: Full (42cc0b0)
03: Full (209e3b909d005905588c2bde2d934d1b23abc527)
02: Full (34a243dd27615b39ecb28d9d8e0009de19091e10)
01: Full (450348c8ede27eeb70426736f309dd2f5e1bafb7)
00: Full (7f21a1e280af62048a4bcb0993ed6448e1fde635)

liach · 2021-01-12T00:40:54Z

/test

openjdk · 2021-01-12T00:41:39Z

@liach you need to get approval to run the tests in tier1 for commits up until 450348c8

liach · 2021-01-12T06:00:39Z

A quick summary:

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. a test case for 1
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.

hns

Thanks for the contribution, this looks good in general.

hns · 2021-01-12T11:57:36Z

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

+            public Boolean visitDeclared(DeclaredType t, Void unused) {
+                // kind 1
+                if (super.visitDeclared(t, unused) || visit(t.getEnclosingType()))
+                    return true;


By convention we always use braces in if-statements.

hns · 2021-01-12T12:09:48Z

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

+
+            @Override
+            public Boolean visitArray(ArrayType t, Void unused) {
+                // 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

hns · 2021-01-12T12:34:44Z

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

@@ -328,6 +328,53 @@ public boolean isAnnotated(TypeMirror e) {
        return !e.getAnnotationMirrors().isEmpty();
    }

+    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.

hns

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.

hns · 2021-01-14T12:32:42Z

.../share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractExecutableMemberWriter.java

        tree.add("this");
    }

+    /**
+     * 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.

hns

Looks good!

openjdk · 2021-01-15T14:01:42Z

@liach This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8259216: javadoc omits method receiver for any nested type annotation

Reviewed-by: hannesw

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 23 new commits pushed to the master branch:

707bce0: 8257212: (bf spec) Clarify byte order of the buffer returned by CharBuffer.subsequence(int,int)
0ec2c96: 8259820: JShell does not handle -source 8 properly
b01a15e: 8258884: [TEST_BUG] Convert applet-based test open/test/jdk/javax/swing/JMenuItem/8031573/bug8031573.java to a regular java test
6d4a593: 8259627: Potential memory leaks in JVMTI after JDK-8227745
2c8e337: 8259622: TreeMap.computeIfAbsent deviates from spec
d701bab: Merge
4307fa6: 8253505: JFR: onFlush invoked out of order with a sorted event stream
0148adf: 8255120: C2: assert(outer->outcnt() >= phis + 2 && outer->outcnt() <= phis + 2 + stores + 1) failed: only phis
90960c5: 8252657: JVMTI agent is not unloaded when Agent_OnAttach is failed
e3b548a: 8257736: InputStream from BodyPublishers.ofInputStream() leaks when IOE happens
... and 13 more: https://git.openjdk.java.net/jdk/compare/ff3e6e46cd2b830e8656934d68e14f89b9095cda...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

As you do not have Committer status in this project an existing Committer must agree to sponsor your change. Possible candidates are the reviewers of this PR (@hns) but any other Committer may sponsor as well.

➡️ To flag this PR as ready for integration with the above commit message, type /integrate in a new comment. (Afterwards, your sponsor types /sponsor in a new comment to perform the integration).

liach · 2021-01-15T14:29:02Z

/integrate

openjdk · 2021-01-15T14:30:00Z

@liach
Your change (at version 42cc0b0) is now ready to be sponsored by a Committer.

hns · 2021-01-15T15:12:01Z

/sponsor

openjdk · 2021-01-15T15:12:50Z

@hns @liach Since your change was applied there have been 25 commits pushed to the master branch:

bcf20a0: 8259777: Incorrect predication condition generated by ADLC
bbac91a: 8257959: Add gtest run with -XX:+UseLargePages
707bce0: 8257212: (bf spec) Clarify byte order of the buffer returned by CharBuffer.subsequence(int,int)
0ec2c96: 8259820: JShell does not handle -source 8 properly
b01a15e: 8258884: [TEST_BUG] Convert applet-based test open/test/jdk/javax/swing/JMenuItem/8031573/bug8031573.java to a regular java test
6d4a593: 8259627: Potential memory leaks in JVMTI after JDK-8227745
2c8e337: 8259622: TreeMap.computeIfAbsent deviates from spec
d701bab: Merge
4307fa6: 8253505: JFR: onFlush invoked out of order with a sorted event stream
0148adf: 8255120: C2: assert(outer->outcnt() >= phis + 2 && outer->outcnt() <= phis + 2 + stores + 1) failed: only phis
... and 15 more: https://git.openjdk.java.net/jdk/compare/ff3e6e46cd2b830e8656934d68e14f89b9095cda...master

Your commit was automatically rebased without conflicts.

Pushed as commit eb7fa00.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

bridgekeeper bot added the oca Needs verification of OCA signatory status label Jan 8, 2021

openjdk bot added the javadoc javadoc-dev@openjdk.org label Jan 8, 2021

bridgekeeper bot added the oca-verify Needs verification of OCA signatory status label Jan 8, 2021

bridgekeeper bot removed oca Needs verification of OCA signatory status oca-verify Needs verification of OCA signatory status labels Jan 11, 2021

openjdk bot added the rfr Pull request is ready for review label Jan 11, 2021

liach force-pushed the bug8259216 branch from 7f21a1e to 450348c Compare January 12, 2021 00:34

openjdk bot added the test-request label Jan 12, 2021

liach force-pushed the bug8259216 branch from 450348c to 34a243d Compare January 12, 2021 05:51

hns reviewed Jan 12, 2021

View reviewed changes

liach force-pushed the bug8259216 branch from 34a243d to 209e3b9 Compare January 12, 2021 15:36

hns reviewed Jan 14, 2021

View reviewed changes

8259216: javadoc omits method receiver for any nested type annotation

42cc0b0

liach force-pushed the bug8259216 branch from 209e3b9 to 42cc0b0 Compare January 14, 2021 13:40

hns approved these changes Jan 15, 2021

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label Jan 15, 2021

openjdk bot added the sponsor Pull request is ready to be sponsored label Jan 15, 2021

openjdk bot closed this Jan 15, 2021

openjdk bot added integrated Pull request has been integrated and removed sponsor Pull request is ready to be sponsored ready Pull request is ready to be integrated rfr Pull request is ready for review labels Jan 15, 2021

8259216: javadoc omits method receiver for any nested type annotation #1997

8259216: javadoc omits method receiver for any nested type annotation #1997

liach commented Jan 8, 2021 •

edited by openjdk bot

bridgekeeper bot commented Jan 8, 2021

openjdk bot commented Jan 8, 2021

liach commented Jan 8, 2021

bridgekeeper bot commented Jan 8, 2021

robilad commented Jan 8, 2021

liach commented Jan 8, 2021

mlbridge bot commented Jan 11, 2021 •

edited

liach commented Jan 12, 2021

openjdk bot commented Jan 12, 2021

liach commented Jan 12, 2021

hns left a comment

hns Jan 12, 2021

hns Jan 12, 2021

liach Jan 12, 2021

hns Jan 12, 2021

liach Jan 12, 2021

hns left a comment

hns Jan 14, 2021

liach Jan 14, 2021

hns left a comment

openjdk bot commented Jan 15, 2021 •

edited

liach commented Jan 15, 2021

openjdk bot commented Jan 15, 2021

hns commented Jan 15, 2021

openjdk bot commented Jan 15, 2021

8259216: javadoc omits method receiver for any nested type annotation #1997

8259216: javadoc omits method receiver for any nested type annotation #1997

Conversation

liach commented Jan 8, 2021 • edited by openjdk bot

Progress

Issue

Reviewers

Download

bridgekeeper bot commented Jan 8, 2021

openjdk bot commented Jan 8, 2021

liach commented Jan 8, 2021

bridgekeeper bot commented Jan 8, 2021

robilad commented Jan 8, 2021

liach commented Jan 8, 2021

mlbridge bot commented Jan 11, 2021 • edited

Webrevs

liach commented Jan 12, 2021

openjdk bot commented Jan 12, 2021

liach commented Jan 12, 2021

hns left a comment

Choose a reason for hiding this comment

hns Jan 12, 2021

Choose a reason for hiding this comment

hns Jan 12, 2021

Choose a reason for hiding this comment

liach Jan 12, 2021

Choose a reason for hiding this comment

hns Jan 12, 2021

Choose a reason for hiding this comment

liach Jan 12, 2021

Choose a reason for hiding this comment

hns left a comment

Choose a reason for hiding this comment

hns Jan 14, 2021

Choose a reason for hiding this comment

liach Jan 14, 2021

Choose a reason for hiding this comment

hns left a comment

Choose a reason for hiding this comment

openjdk bot commented Jan 15, 2021 • edited

liach commented Jan 15, 2021

openjdk bot commented Jan 15, 2021

hns commented Jan 15, 2021

openjdk bot commented Jan 15, 2021

liach commented Jan 8, 2021 •

edited by openjdk bot

mlbridge bot commented Jan 11, 2021 •

edited

openjdk bot commented Jan 15, 2021 •

edited