JDK 15 initial RFR of 8193553: Provide better guidance on using javax.lang.model visitors

[Joe Darcy]

Hello,

Please review the initial fix for

     8193553 : Provide better guidance on using javax.lang.model visitors
     http://cr.openjdk.java.net/~darcy/8193553.0/

Once wording is agree to for the element visitor case, I'll write 
analogous additions for the type visitor and annotation value visitor 
classes and send around the set of changes for another round of review.

Thanks,

-Joe

--- 
old/src/java.compiler/share/classes/javax/lang/model/element/ElementVisitor.java 
2020-02-21 09:33:06.898482673 -0800
+++ 
new/src/java.compiler/share/classes/javax/lang/model/element/ElementVisitor.java 
2020-02-21 09:33:06.598482673 -0800
@@ -64,6 +64,53 @@
   * packages that are only required to run on Java SE 8 and higher
   * platform versions.
   *
+ * @apiNote
+ *
+ * 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
+ * {@linkplain javax.lang.model.SourceVersion source version} the
+ * visitor is appropriate for.
+ *
+ * That is, a {@code FooVisitor}<i>N</i> is expected
+ * to handle all language constructs present in source version
+ * <i>N</i>. If there are no new language constructs added in version
+ * <i>N</i> + 1 (or subsequent releases), {@code
+ * FooVisitor}<i>N</i> may also handle that later source version; in
+ * that case, the {@link
+ * javax.annotation.processing.SupportedSourceVersion
+ * SupportedSourceVersion} annotation on the {@code
+ * FooVisitor}<i>N</i> class will indicate a later version.
+ *
+ * When visiting an element representing a language construct
+ * introduced <em>after</em> source version <i>N</i>, a {@code
+ * FooVisitor}<i>N</i> will throw an {@link UnknownElementException}
+ * unless that behavior is overridden.
+ *
+ * <p>When choosing which member of a visitor family to subclass,
+ * subclassing the most recent one increases the range of source
+ * versions covered. When choosing which visitor family to subclass,
+ * consider their built-in capabilities:
+ *
+ * <ul>
+ *
+ * <li>{@link AbstractElementVisitor6 AbstractElementVisitor}s:
+ * Skeletal visitor implementations.
+ *
+ * <li>{@link SimpleElementVisitor6 SimpleElementVisitor}s: Support
+ * default actions and a default return value.
+ *
+ * <li>{@link ElementKindVisitor6 ElementKindVisitor}s: Visit methods
+ * provided on a {@linkplain Element#getKind per-kind} granularity as
+ * some categories of elements can have more than one kind.
+ *
+ * <li>{@link ElementScanner6 ElementScanner}s: Scanners are visitors
+ * which traverse an element and the elements {@linkplain
+ * Element#getEnclosedElements enclosed} by it and associated with it.
+ *
+ * </ul>
+ *
   * @param <R> the return type of this visitor's methods. Use {@link
   *            Void} for visitors that do not need to return results.
   * @param <P> the type of the additional parameter to this visitor's