[jdk18] RFR: JDK-8273452: DocTrees.getDocCommentTree should be specified as idempotent

[Jonathan Gibbons]

On Thu, 16 Dec 2021 11:05:01 GMT, Hannes Wallnöfer <hannesw at 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