JDK 15 RFR of JDK-8240130: Improve and update discussion of visitor evolution warnings

[Joe Darcy]

Hello,

Please review the documentation changes for

     JDK-8240130: Improve and update discussion of visitor evolution 
warnings
     http://cr.openjdk.java.net/~darcy/8240130.0/

Patch below. Some discussion of and rationale for the changes, the 
original javax.lang.model visitor interfaces and concrete visitor types 
had various warning about the unusual compatibility policies those types 
would use. Unlike other post-Java SE 6 era types, it was anticipated 
methods would be added to interfaces. Prior to default methods in JDK 8, 
such additions were a highly unusual occurrence for public types in the 
JDK. After default methods were used commonly in jDK 8, such additions 
are of less concern. The risk of a true source compatibility is also low 
for a new "visitFoo" method since it will have a parameter of type Foo, 
which is new to the release, and thus not have an overloading conflict 
with a method in an existing visitor outside of the JDK.

The warnings are thus toned down and adjusted to note that the 
envisioned additions have already occurred for prior language additions. 
For example, the current policy is only to deprecate the constructors of 
obsolete visitor classes rather than the whole class. The "directly or 
indirectly call" visitUnknown is to accurately describe, but not limit 
to, the current policy of the visitFoo methods in affected concrete 
visitors calling the visitFoo default method on the *interface*, which 
in turn calls visitUnknown.

The warning text is pulled into an apiNote to avoid getting 
inherit-doc-ed for any subclasses. Once the shape of the changes for the 
interface and visitor classes are agree to, I'll replicated the changes 
for the other types.

Thanks,

-Joe

--- 
old/src/java.compiler/share/classes/javax/lang/model/element/ElementVisitor.java 
2020-02-26 13:13:00.848880601 -0800
+++ 
new/src/java.compiler/share/classes/javax/lang/model/element/ElementVisitor.java 
2020-02-26 13:13:00.512880601 -0800
@@ -40,10 +40,17 @@
   * is {@code null}; see documentation of the implementing class for
   * details.
   *
- * <p> <b>WARNING:</b> It is possible that methods will be added to
+ * @apiNote
+ *
+ * WARNING: It is possible that methods will be added to
   * this interface to accommodate new, currently unknown, language
   * structures added to future versions of the Java™ programming
- * language.  Therefore, visitor classes directly implementing this
+ * language.
+ *
+ * Such additions have already occurred to support language features
+ * added after this API was introduced.
+ *
+ * Visitor classes directly implementing this
   * interface may be source incompatible with future versions of the
   * platform.  To avoid this source incompatibility, visitor
   * implementations are encouraged to instead extend the appropriate
@@ -52,21 +59,15 @@
   * parameters, return type, etc. rather than one of the abstract
   * classes.
   *
- * <p>Note that methods to accommodate new language constructs could
- * be added in a source <em>compatible</em> way if they were added as
- * <em>default methods</em>.  However, default methods are only
- * available on Java SE 8 and higher releases and the {@code
- * javax.lang.model.*} packages bundled in Java SE 8 were required to
- * also be runnable on Java SE 7.  Therefore, default methods
- * were <em>not</em> used when extending {@code javax.lang.model.*}
- * to cover Java SE 8 language features.  However, default methods
- * are used in subsequent revisions of the {@code javax.lang.model.*}
- * packages that are only required to run on Java SE 8 and higher
- * platform versions.
- *
- * @apiNote
+ * <p>Methods to accommodate new language constructs are expected to
+ * be added as default methods to provide strong source compatibility,
+ * as done for {@link visitModule visitModule}. The implementations of
+ * the default methods will in turn call {@link visitUnknown
+ * visitUnknown}, behavior that will be overridden in concrete
+ * visitors supporting the source version with the new language
+ * construct.
   *
- * There are several families of classes implementing this visitor
+ * <p>There are several families of classes implementing this visitor
   * interface in the {@linkplain javax.lang.model.util util
   * package}. The families follow a naming pattern along the lines of
   * {@code FooVisitor}<i>N</i> where <i>N</i> indicates the
--- 
old/src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor6.java 
2020-02-26 13:13:01.560880601 -0800
+++ 
new/src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor6.java 
2020-02-26 13:13:01.196880601 -0800
@@ -36,7 +36,9 @@
   * appropriate for the {@link SourceVersion#RELEASE_6 RELEASE_6}
   * source version.
   *
- * <p> <b>WARNING:</b> The {@code ElementVisitor} interface
+ * @apiNote
+ *
+ * <strong>WARNING:</strong> The {@code ElementVisitor} interface
   * implemented by this class may have methods added to it in the
   * future to accommodate new, currently unknown, language structures
   * added to future versions of the Java™ programming language.
@@ -46,12 +48,12 @@
   * methods with names beginning with {@code "visit"}.
   *
   * <p>When such a new visit method is added, the default
- * implementation in this class will be to call the {@link
+ * implementation in this class will be to directly or indirectly call 
the {@link
   * #visitUnknown visitUnknown} method.  A new abstract element visitor
   * class will also be introduced to correspond to the new language
   * level; this visitor will have different default behavior for the
- * visit method in question.  When the new visitor is introduced, all
- * or portions of this visitor may be deprecated.
+ * visit method in question.  When a new visitor is introduced,
+ * portions of this visitor class may be deprecated, including its 
constructors.
   *
   * @param <R> the return type of this visitor's methods. Use {@link
   *            Void} for visitors that do not need to return results.