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

JDK-8263043: Add test to verify order of tag output #2835

Closed
wants to merge 5 commits into from

Conversation

jonathan-gibbons
Copy link
Contributor

@jonathan-gibbons jonathan-gibbons commented Mar 4, 2021

Please review a new test to verify that the output of block tags is generated in the expected order.

The code in the standard doclet to generate the output is the same for all use sites (modules, packages, class, members) and so just the richest site is tested.

The test checks that tags appear in the expected order by default, but can be reordered in a couple of different ways.


Progress

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

Issue

Reviewers

Download

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

@bridgekeeper
Copy link

bridgekeeper bot commented Mar 4, 2021

👋 Welcome back jjg! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

@openjdk
Copy link

openjdk bot commented Mar 4, 2021

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

@openjdk openjdk bot added the javadoc javadoc-dev@openjdk.org label Mar 4, 2021
@openjdk openjdk bot added the rfr Pull request is ready for review label Mar 4, 2021
@mlbridge
Copy link

mlbridge bot commented Mar 4, 2021

Webrevs

Comment on lines 49 to 50
* There is a default order, embodies in the order of declaration of tags in
* {@code Tagl;etManager}, but this can be overridden on the command line by
Copy link
Member

Choose a reason for hiding this comment

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

Typo: "Tagl;etManager". Grammar: "embodies" does not seem to fit into the context.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

oops. will fix

* Tests the order of the output of block tags in the generated output.
* There is a default order, embodies in the order of declaration of tags in
* {@code Tagl;etManager}, but this can be overridden on the command line by
* specifying {@code -tag} options in the desired order.
Copy link
Member

Choose a reason for hiding this comment

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

I didn't know you could reorder standard tags using that option for custom tags. Although I found the relevant section in the manual, we should separately consider improving output from javadoc -h to reflect such use of -tag:

    -tag <name>:<locations>:<header>
                  Specify single argument custom tags

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Hmm. Noted. At a minimum this will be good for the man page updates. I'll see if we can update command-line help in a reasonable way as well.

Comment on lines +70 to +76
* This is method m.
* @param p1 first parameter
* @param p2 second parameter
* @return zero
* @throws IllegalArgumentException well, never
* @since 1.0
* @see <a href="http://example.com">example</a>
Copy link
Member

Choose a reason for hiding this comment

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

Consider adding @version and @author standard tags to this test. Although JDK API documentation does not include those, API documentation of other projects might. Adding those tags will improve coverage.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Hmmm ...
Actually, my initial version of the code did include @author, but not @version. But, it didn't work as expected ... because neither are actually supported on methods, and so they do not appear in the output. See https://docs.oracle.com/en/java/javase/15/docs/specs/javadoc/doc-comment-spec.html#where-tags-can-be-used

So, if you really think we should test these as well, we will have to extend the test to include comments on a class or interface declaration.

Copy link
Member

Choose a reason for hiding this comment

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

I looked at that table before suggesting to add those tags and realized that adding them would complicate the test, hence "consider". You could push the test as is and we will improve it later. It's up to you, Jon.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I've improved the test.

@openjdk
Copy link

openjdk bot commented Mar 5, 2021

@jonathan-gibbons 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:

8263043: Add test to verify order of tag output

Reviewed-by: prappo

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 6 new commits pushed to the master branch:

  • 7182985: 8263104: fix warnings for empty paragraphs
  • 5eb2091: 8261689: javax/swing/JComponent/7154030/bug7154030.java still fails with "Exception: Failed to hide opaque button"
  • 75a5be8: 8263054: [testbug] SharedArchiveConsistency.java reuses jsa files
  • 2afbd5d: 8250804: Can't set the application icon image for Unity WM on Linux.
  • fa43f92: 8261845: File permissions of packages built by jpackage
  • 23ee60d: 8261008: Optimize Xor

Please see this link for an up-to-date comparison between the source branch of this pull request and the master branch.
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.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

@openjdk openjdk bot added the ready Pull request is ready to be integrated label Mar 5, 2021
Copy link
Member

@pavelrappo pavelrappo left a comment

Choose a reason for hiding this comment

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

The improved version looks better. Thanks.

@jonathan-gibbons
Copy link
Contributor Author

/integrate

@openjdk openjdk bot removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Mar 6, 2021
@openjdk
Copy link

openjdk bot commented Mar 6, 2021

@jonathan-gibbons Your integration request cannot be fulfilled at this time, as the status check jcheck did not complete successfully

@openjdk openjdk bot added ready Pull request is ready to be integrated rfr Pull request is ready for review labels Mar 6, 2021
@jonathan-gibbons
Copy link
Contributor Author

/integrate

@openjdk openjdk bot closed this Mar 6, 2021
@openjdk openjdk bot added integrated Pull request has been integrated and removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Mar 6, 2021
@openjdk
Copy link

openjdk bot commented Mar 6, 2021

@jonathan-gibbons Since your change was applied there have been 6 commits pushed to the master branch:

  • 7182985: 8263104: fix warnings for empty paragraphs
  • 5eb2091: 8261689: javax/swing/JComponent/7154030/bug7154030.java still fails with "Exception: Failed to hide opaque button"
  • 75a5be8: 8263054: [testbug] SharedArchiveConsistency.java reuses jsa files
  • 2afbd5d: 8250804: Can't set the application icon image for Unity WM on Linux.
  • fa43f92: 8261845: File permissions of packages built by jpackage
  • 23ee60d: 8261008: Optimize Xor

Your commit was automatically rebased without conflicts.

Pushed as commit f2d0152.

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

@jonathan-gibbons jonathan-gibbons deleted the tag-order branch March 6, 2021 15:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
integrated Pull request has been integrated javadoc javadoc-dev@openjdk.org
2 participants