8273452: DocTrees.getDocCommentTree should be specified as idempotent

Reviewed-by: jjg

Author: hns

src/jdk.compiler/share/classes/com/sun/source/util/DocTrees.java

@@ -87,6 +87,11 @@ public static DocTrees instance(ProcessingEnvironment env) {
     /**
      * Returns the doc comment tree, if any, for the Tree node identified by a given TreePath.
      * Returns {@code null} if no doc comment was found.
+     *
+     * @implNote The default implementation of this method returns the same
+     * {@code DocCommentTree} instance for repeated invocations
+     * with the same argument.
+     *
      * @param path the path for the tree node
      * @return the doc comment tree
      */
@@ -95,6 +100,11 @@ public static DocTrees instance(ProcessingEnvironment env) {
     /**
      * Returns the doc comment tree of the given element.
      * Returns {@code null} if no doc comment was found.
+     *
+     * @implNote The default implementation of this method returns the same
+     * {@code DocCommentTree} instance for repeated invocations
+     * with the same argument.
+     *
      * @param e an element whose documentation is required
      * @return the doc comment tree
      *
@@ -109,6 +119,9 @@ public static DocTrees instance(ProcessingEnvironment env) {
      * Returns {@code null} if no doc comment was found.
      * Future releases may support additional file types.
      *
+     * @implNote The default implementation of this method returns a
+     * new {@code DocCommentTree} instance for each invocation.
+     *
      * @param fileObject the content container
      * @return the doc comment tree
      * @since 9
@@ -123,6 +136,9 @@ public static DocTrees instance(ProcessingEnvironment env) {
      * Returns {@code null} if no doc comment was found.
      * Future releases may support additional file types.
      *
+     * @implNote The default implementation of this method returns a
+     * new {@code DocCommentTree} instance for each invocation.
+     *
      * @param e an element whose path is used as a reference
      * @param relativePath the relative path from the Element
      * @return the doc comment tree