8267832: SimpleVisitors and Scanners in jdk.compiler should use @implSpec

[lahodaj]

As noted in:
https://bugs.openjdk.java.net/browse/JDK-8265981?focusedCommentId=14423316&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-14423316

Methods in various utility visitor classes in jdk.compiler should use @implSpec to specify the implementation behavior. This patch tries to add the @implSpec tag to methods which already contain a text specifying the implementation, and adds new javadoc to the handful of methods that are missing it so far.

The CSR is started for review here:
https://bugs.openjdk.java.net/browse/JDK-8267838

---

Progress

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

Issue

• JDK-8267832: SimpleVisitors and Scanners in jdk.compiler should use @implSpec

Reviewers

• Pavel Rappo (@pavelrappo - Reviewer) ⚠️ Review applies to 5c9f694
• Joe Darcy (@jddarcy - Reviewer) ⚠️ Review applies to 5c9f694

Reviewing

Using git

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

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

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 4223

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

Using diff file

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

[bridgekeeper]

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

[openjdk]

@lahodaj The following labels will be automatically applied to this pull request:

• compiler
• javadoc

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

[mlbridge]

Webrevs

• 02: Full (7cea033a)
• 01: Full - Incremental (5c9f694f)
• 00: Full (d27a84a0)

[pavelrappo]

I wish we had a better class-level (Doc)TreeScanner doc comment. That would allow to avoid most of the repetition in method-level comments, the vast majority of which are there only to say that the children are scanned in left to right order.

[pavelrappo]

1. Should the error-counting example in the immediately following paragraph belong to this @implSpec section?
2. Why is there no similar @implSpec section being added to the class-level doc comment of TreeScanner? If such a section is to be added, then should the identifier-counting example in the immediately following paragraph belong to that section?

[lahodaj]

Thanks for the comment, Pavel. I've tried to do the changes in an update:
5c9f694

[openjdk-notifier]

The dependent pull request has now been integrated, and the target branch of this pull request has been updated. This means that changes from the dependent pull request can start to show up as belonging to this pull request, which may be confusing for reviewers. To remedy this situation, simply merge the latest changes from the new target branch into this pull request by running commands similar to these in the local repository for your personal fork:

git checkout JDK-8262891
git fetch https://git.openjdk.java.net/jdk master
git merge FETCH_HEAD
# if there are conflicts, follow the instructions given by git merge
git commit -m "Merge master"
git push

[openjdk]

@lahodaj this pull request can not be integrated into master due to one or more merge conflicts. To resolve these merge conflicts and update this pull request you can run the following commands in the local repository for your personal fork:

git checkout JDK-8267832
git fetch https://git.openjdk.java.net/jdk master
git merge FETCH_HEAD
# resolve conflicts and follow the instructions given by git merge
git commit -m "Merge master"
git push

[openjdk]

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

8267832: SimpleVisitors and Scanners in jdk.compiler should use @implSpec

Reviewed-by: prappo, darcy

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.

[lahodaj]

/integrate

[openjdk]

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

• 8130be5: 8268318: Missing comma in copyright header
• b09d8b9: 8267926: AsyncLogGtest.java fails on assert with: decorator was not part of the decorator set specified at creation.
• 5ebd419: 8267972: Inline cache cleaning is not monotonic
• 6d1f3ac: 8149138: [javadoc] Fix SerialFormBuilder eliminate String bashing
• 58bdabc: 8268164: Adopt cast notation for WorkerThread conversions
• 9fc914b: 8204686: Dynamic parallel reference processing support for Parallel GC

Your commit was automatically rebased without conflicts.

Pushed as commit e4d0454.

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