On Thu, 16 Dec 2021 11:05:01 GMT, Hannes Wallnöfer <hann...@openjdk.org> wrote:
> Please review a doc-only change to add implementation notes to the > `DocTrees.getDocCommentTree` methods, some of which return the same > `DocCommentTree` instance on repeated invocation and some don't. I decided to > use `@implNote` instead of `@implSpec` as usually I wouldn't expect object > identity to be part of a Java API specification. > > I verified the described behavior using code analysis and enhancing existing > tests. The latter are not included in the commit as this is a `noreg-doc` > issue. I guess it's a gray area whether it should be an `implSpec` or an `implNote`. It is a relatively important aspect of the API, because the operations are expensive, and even cause some downstream caching. For now, it's enough that it is noted in some fashion. As a general style note, I would suggest a blank line before each `implNote`, and change "The implementation of this method" to either "The default implementation of this method" or just "This implementation". ------------- Marked as reviewed by jjg (Reviewer). PR: https://git.openjdk.java.net/jdk18/pull/36
