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

jonathan-gibbons · 2021-03-04T21:12:15Z

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

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

Reviewers

Pavel Rappo (@pavelrappo - Reviewer) ⚠️ Review applies to 395cca1

Download

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

bridgekeeper · 2021-03-04T21:12:26Z

👋 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 · 2021-03-04T21:13:41Z

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

mlbridge · 2021-03-04T21:21:05Z

Webrevs

pavelrappo · 2021-03-05T11:21:20Z

test/langtools/jdk/javadoc/doclet/testTagOrder/TestTagOrder.java

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


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

oops. will fix

pavelrappo · 2021-03-05T11:47:54Z

test/langtools/jdk/javadoc/doclet/testTagOrder/TestTagOrder.java

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


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

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.

pavelrappo · 2021-03-05T12:41:48Z

test/langtools/jdk/javadoc/doclet/testTagOrder/TestTagOrder.java

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


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.

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.

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.

I've improved the test.

openjdk · 2021-03-05T12:44:26Z

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

… class comments

pavelrappo

The improved version looks better. Thanks.

jonathan-gibbons · 2021-03-05T19:28:00Z

/integrate

openjdk · 2021-03-06T09:12:00Z

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

Fix whitespace

jonathan-gibbons · 2021-03-06T15:23:59Z

/integrate

openjdk · 2021-03-06T15:24:56Z

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

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

8fcdc22

openjdk bot added the javadoc javadoc-dev@openjdk.org label Mar 4, 2021

fix whitespace

3d3bdf9

openjdk bot added the rfr Pull request is ready for review label Mar 4, 2021

pavelrappo approved these changes Mar 5, 2021

View reviewed changes

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

jonathan-gibbons added 2 commits March 5, 2021 08:34

Merge remote-tracking branch 'upstream/master' into tag-order

661ab30

Address review comments; extend test to check @author and @Version in…

395cca1

… class comments

pavelrappo approved these changes Mar 5, 2021

View reviewed changes

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

Update TestTagOrder.java

8ad33ab

Fix whitespace

openjdk bot added ready Pull request is ready to be integrated rfr Pull request is ready for review labels Mar 6, 2021

openjdk bot closed this Mar 6, 2021

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

jonathan-gibbons deleted the tag-order branch March 6, 2021 15:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

jonathan-gibbons commented Mar 4, 2021 •

edited by openjdk bot

Loading

bridgekeeper bot commented Mar 4, 2021

openjdk bot commented Mar 4, 2021

mlbridge bot commented Mar 4, 2021 •

edited

Loading

pavelrappo Mar 5, 2021

jonathan-gibbons Mar 5, 2021

pavelrappo Mar 5, 2021

jonathan-gibbons Mar 5, 2021

pavelrappo Mar 5, 2021

jonathan-gibbons Mar 5, 2021

pavelrappo Mar 5, 2021

jonathan-gibbons Mar 5, 2021

openjdk bot commented Mar 5, 2021 •

edited

Loading

pavelrappo left a comment

jonathan-gibbons commented Mar 5, 2021

openjdk bot commented Mar 6, 2021

jonathan-gibbons commented Mar 6, 2021

openjdk bot commented Mar 6, 2021

		* 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

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

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

Conversation

jonathan-gibbons commented Mar 4, 2021 • edited by openjdk bot Loading

Progress

Issue

Reviewers

Download

bridgekeeper bot commented Mar 4, 2021

openjdk bot commented Mar 4, 2021

mlbridge bot commented Mar 4, 2021 • edited Loading

Webrevs

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

openjdk bot commented Mar 5, 2021 • edited Loading

pavelrappo left a comment

Choose a reason for hiding this comment

jonathan-gibbons commented Mar 5, 2021

openjdk bot commented Mar 6, 2021

jonathan-gibbons commented Mar 6, 2021

openjdk bot commented Mar 6, 2021

jonathan-gibbons commented Mar 4, 2021 •

edited by openjdk bot

Loading

mlbridge bot commented Mar 4, 2021 •

edited

Loading

openjdk bot commented Mar 5, 2021 •

edited

Loading