Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
wants to merge 1 commit into from

Conversation

@liach
Copy link
Contributor

@liach liach commented Jan 8, 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>.@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

Download

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

@bridgekeeper bridgekeeper bot added the oca label Jan 8, 2021
@bridgekeeper
Copy link

@bridgekeeper bridgekeeper bot commented Jan 8, 2021

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.

Loading

@openjdk
Copy link

@openjdk openjdk bot commented Jan 8, 2021

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

Loading

@openjdk openjdk bot added the javadoc label Jan 8, 2021
@liach
Copy link
Contributor Author

@liach liach commented Jan 8, 2021

/signed

Loading

@bridgekeeper
Copy link

@bridgekeeper bridgekeeper bot commented Jan 8, 2021

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!

Loading

@robilad
Copy link

@robilad robilad commented Jan 8, 2021

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

Loading

@liach
Copy link
Contributor Author

@liach liach commented Jan 8, 2021

Done.

Loading

@mlbridge
Copy link

@mlbridge mlbridge bot commented Jan 11, 2021

Webrevs

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

Loading

@liach
Copy link
Contributor Author

@liach liach commented Jan 12, 2021

/test

Loading

@openjdk
Copy link

@openjdk openjdk bot commented Jan 12, 2021

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

Loading

@liach
Copy link
Contributor Author

@liach liach commented Jan 12, 2021

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

Loading

Copy link
Member

@hns hns left a comment

Thanks for the contribution, this looks good in general.

Loading

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

@hns hns Jan 12, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

By convention we always use braces in if-statements.

Loading


@Override
public Boolean visitArray(ArrayType t, Void unused) {
// kind 0
Copy link
Member

@hns hns Jan 12, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Loading

Copy link
Contributor Author

@liach liach Jan 12, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Loading

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

public boolean isRecursivelyAnnotated(TypeMirror e) {
Copy link
Member

@hns hns Jan 12, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Loading

Copy link
Contributor Author

@liach liach Jan 12, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Loading

Copy link
Member

@hns hns left a comment

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.

Loading

tree.add("this");
}

/**
* Returns if a receiver type is annotated anywhere in its type for
Copy link
Member

@hns hns Jan 14, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Loading

Copy link
Contributor Author

@liach liach Jan 14, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done. Rebased to fix merge conflict as well.

Loading

hns
hns approved these changes Jan 15, 2021
Copy link
Member

@hns hns left a comment

Looks good!

Loading

@openjdk
Copy link

@openjdk openjdk bot commented Jan 15, 2021

@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).

Loading

@openjdk openjdk bot added the ready label Jan 15, 2021
@liach
Copy link
Contributor Author

@liach liach commented Jan 15, 2021

/integrate

Loading

@openjdk openjdk bot added the sponsor label Jan 15, 2021
@openjdk
Copy link

@openjdk openjdk bot commented Jan 15, 2021

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

Loading

@hns
Copy link
Member

@hns hns commented Jan 15, 2021

/sponsor

Loading

@openjdk
Copy link

@openjdk openjdk bot commented Jan 15, 2021

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

Loading

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
3 participants