On Thu, 27 May 2021 09:41:17 GMT, Jan Lahoda <[email protected]> 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
