8193553: Provide better guidance on using javax.lang.model visitors

Reviewed-by: jjg

src/java.compiler/share/classes/javax/lang/model/element/AnnotationValueVisitor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2020, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -27,9 +27,8 @@
 
 
 import java.util.List;
-
 import javax.lang.model.type.TypeMirror;
-
+import javax.lang.model.util.*;
 
 /**
  * A visitor of the values of annotation type elements, using a
@@ -73,6 +72,46 @@
  * 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.
+ *
+ * In particular, 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>&nbsp;+&nbsp;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 annotation value representing a language construct
+ * introduced <strong>after</strong> source version <i>N</i>, a {@code
+ * FooVisitor}<i>N</i> will throw an {@link
+ * UnknownAnnotationValueException} 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 AbstractAnnotationValueVisitor6
+ * AbstractAnnotationValueVisitor}s: Skeletal visitor implementations.
+ *
+ * <li>{@link SimpleAnnotationValueVisitor6
+ * SimpleAnnotationValueVisitor}s: Support default actions and a
+ * default return value.
+ *
+ * </ul>
+ *
  * @param <R> the return type of this visitor's methods
  * @param <P> the type of the additional parameter to this visitor's methods.
  * @author Joseph D. Darcy

src/java.compiler/share/classes/javax/lang/model/element/ElementVisitor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2020, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -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.
+ *
+ * In particular, 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>&nbsp;+&nbsp;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 <strong>after</strong> 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

src/java.compiler/share/classes/javax/lang/model/type/TypeVisitor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2020, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -26,6 +26,7 @@
 package javax.lang.model.type;
 
 import javax.lang.model.element.*;
+import javax.lang.model.util.*;
 
 /**
  * A visitor of types, in the style of the
@@ -64,6 +65,49 @@
  * 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.
+ *
+ * In particular, 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>&nbsp;+&nbsp;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 a type representing a language construct
+ * introduced <strong>after</strong> source version <i>N</i>, a {@code
+ * FooVisitor}<i>N</i> will throw an {@link UnknownTypeException}
+ * 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 AbstractTypeVisitor6 AbstractTypeVisitor}s:
+ * Skeletal visitor implementations.
+ *
+ * <li>{@link SimpleTypeVisitor6 SimpleTypeVisitor}s: Support
+ * default actions and a default return value.
+ *
+ * <li>{@link TypeKindVisitor6 TypeKindVisitor}s: Visit methods
+ * provided on a {@linkplain TypeMirror#getKind per-kind} granularity
+ * as some categories of types can have more than one kind.
+ *
+ * </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