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

[Pavel Rappo]

On Thu, 27 May 2021 09:41:17 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

> 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

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.

src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java line 38:

> 36:  * nodes.
> 37:  *
> 38:  * @implSpec

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?

-------------

PR: https://git.openjdk.java.net/jdk/pull/4223