JDK-8272853: improve JavadocTester.runTests

[jonathan-gibbons]

Please review a medium simple test-only fix to improve the JavadocTester runTests methods.

Currently, there are two overloads: one to invoke no-args test methods, and another to invoke test methods with args, such as a method-specific Path. This latter one is slightly inconvenient to use, since it requires the boilerplate use of a function to create the arguments.

The first overload is updated in a backwards compatible way, to examine the parameters of methods annotated with @Test, and to recognize common patterns: namely no-args methods and (Path) methods, without the need for any additional function. The second overload is retained by backwards compatibility, until if and when we decide it is no longer required.

In addition, two new overloads are added, similar to the first two, but with the addition of an extra parameter to decide which methods should be invoked. This is primarily a debugging aid. Using these overloads, it is easy to specify, on the command line used to run the test, the methods to be executed.

A new test is added to test the new functionality.

---

Progress

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

Issue

• JDK-8272853: improve JavadocTester.runTests

Reviewers

• Hannes Wallnöfer (@hns - Reviewer) ⚠️ Review applies to 4387813

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.java.net/jdk pull/6983/head:pull/6983
$ git checkout pull/6983

Update a local copy of the PR:
$ git checkout pull/6983
$ git pull https://git.openjdk.java.net/jdk pull/6983/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 6983

View PR using the GUI difftool:
$ git pr show -t 6983

Using diff file

Download this PR as a diff file:
https://git.openjdk.java.net/jdk/pull/6983.diff

[bridgekeeper]

👋 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]

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

Webrevs

• 02: Full - Incremental (5fbaeb03)
• 01: Full - Incremental (ee672346)
• 00: Full (43878135)

[hns]

Making the boilerplate to call test methods with a path object obsolete is a very welcome enhancement. Can and should we update existing tests that use the explicit method -> path function to the new form?

You say that the new forms that take a list of method names could be used by passing the method names as command line arguments. That functionality is not included in this PR as far as I can see. Is that planned for a later time?

[bridgekeeper]

@jonathan-gibbons This pull request has been inactive for more than 4 weeks and will be automatically closed if another 4 weeks passes without any activity. To avoid this, simply add a new comment to the pull request. Feel free to ask for assistance if you need help with progressing this pull request towards integration!

[hns]

Sorry for letting this linger for so long. I asked some questions in the comments, but that was not meant to block the PR. The changes look good to me.

[openjdk]

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

8272853: improve `JavadocTester.runTests`

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 no new commits pushed to the master branch. If another commit should be pushed before you perform the /integrate command, your PR will be automatically rebased. If you prefer to avoid any potential 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.

[jonathan-gibbons]

@hns I tweaked the new "self-test" to address failures seen on some platforms.
I weakened the constraint that IllegalArgumentException should always be thrown before any sub-tests are executed. While this may be good as a general principle, it doesn't work so well when the ILA comes from a nested call. Rather than twist the code so that ILA is always thrown early, I left JavadocTester alone, and just relaxed the code in TestRunTests.java to allow ILA to be thrown later, in some situations.

FWIW, the issue did not show up earlier, because the order of methods returned by getDeclaredMethods is explicitly undefined and may vary across platforms.

[hns]

Thanks for the explanation, looks good to me!

[jonathan-gibbons]

/integrate

[openjdk]

Going to push as commit b0028a4.
Since your change was applied there have been 28 commits pushed to the master branch:

• e07fd39: 8281181: Do not use CPU Shares to compute active processor count
• 9c817d3: 8015854: [macosx] JButton's HTML ImageView adding unwanted padding
• 733c790: 8282081: java.time.DateTimeFormatter: wrong definition of symbol F
• f9f9c0a: 8252769: Warn in configure if git config autocrlf has invalid value
• 603050b: 8282661: [BACKOUT] ByteBufferTest.java: replace endless recursion with RuntimeException in void ck(double x, double y)
• 5247153: 8282615: G1: Fix some includes
• a584c90: 8282573: ByteBufferTest.java: replace endless recursion with RuntimeException in void ck(double x, double y)
• d5e8e52: 8282532: Allow explicitly setting build platform alongside --openjdk-target
• b383780: 8282343: Create a regression test for JDK-4518432
• b629782: 8279886: C1: Turn off SelectivePhiFunctions in presence of irreducible loops
• ... and 18 more: https://git.openjdk.java.net/jdk/compare/b6c35ae44aeb31deb7a15ee2939156ed00b3df52...master

Your commit was automatically rebased without conflicts.

[openjdk]

@jonathan-gibbons Pushed as commit b0028a4.

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