changeset 60487:332ee3137fb8

8240130: Improve and update discussion of visitor evolution warnings Reviewed-by: jjg
author darcy
date Sat, 14 Mar 2020 09:53:43 -0700
parents 10f11578b1f4
children 0d7a66c27369
files src/java.compiler/share/classes/javax/lang/model/element/AnnotationValueVisitor.java src/java.compiler/share/classes/javax/lang/model/element/ElementVisitor.java src/java.compiler/share/classes/javax/lang/model/type/TypeVisitor.java src/java.compiler/share/classes/javax/lang/model/util/AbstractAnnotationValueVisitor14.java src/java.compiler/share/classes/javax/lang/model/util/AbstractAnnotationValueVisitor6.java src/java.compiler/share/classes/javax/lang/model/util/AbstractAnnotationValueVisitor7.java src/java.compiler/share/classes/javax/lang/model/util/AbstractAnnotationValueVisitor8.java src/java.compiler/share/classes/javax/lang/model/util/AbstractAnnotationValueVisitor9.java src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor14.java src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor6.java src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor7.java src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor8.java src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor9.java src/java.compiler/share/classes/javax/lang/model/util/AbstractTypeVisitor14.java src/java.compiler/share/classes/javax/lang/model/util/AbstractTypeVisitor6.java src/java.compiler/share/classes/javax/lang/model/util/AbstractTypeVisitor7.java src/java.compiler/share/classes/javax/lang/model/util/AbstractTypeVisitor8.java src/java.compiler/share/classes/javax/lang/model/util/AbstractTypeVisitor9.java src/java.compiler/share/classes/javax/lang/model/util/ElementKindVisitor14.java src/java.compiler/share/classes/javax/lang/model/util/ElementKindVisitor6.java src/java.compiler/share/classes/javax/lang/model/util/ElementKindVisitor7.java src/java.compiler/share/classes/javax/lang/model/util/ElementKindVisitor8.java src/java.compiler/share/classes/javax/lang/model/util/ElementKindVisitor9.java src/java.compiler/share/classes/javax/lang/model/util/ElementScanner14.java src/java.compiler/share/classes/javax/lang/model/util/ElementScanner6.java src/java.compiler/share/classes/javax/lang/model/util/ElementScanner7.java src/java.compiler/share/classes/javax/lang/model/util/ElementScanner8.java src/java.compiler/share/classes/javax/lang/model/util/ElementScanner9.java src/java.compiler/share/classes/javax/lang/model/util/SimpleAnnotationValueVisitor14.java src/java.compiler/share/classes/javax/lang/model/util/SimpleAnnotationValueVisitor6.java src/java.compiler/share/classes/javax/lang/model/util/SimpleAnnotationValueVisitor7.java src/java.compiler/share/classes/javax/lang/model/util/SimpleAnnotationValueVisitor8.java src/java.compiler/share/classes/javax/lang/model/util/SimpleAnnotationValueVisitor9.java src/java.compiler/share/classes/javax/lang/model/util/SimpleElementVisitor14.java src/java.compiler/share/classes/javax/lang/model/util/SimpleElementVisitor6.java src/java.compiler/share/classes/javax/lang/model/util/SimpleElementVisitor7.java src/java.compiler/share/classes/javax/lang/model/util/SimpleElementVisitor8.java src/java.compiler/share/classes/javax/lang/model/util/SimpleElementVisitor9.java src/java.compiler/share/classes/javax/lang/model/util/SimpleTypeVisitor14.java src/java.compiler/share/classes/javax/lang/model/util/SimpleTypeVisitor6.java src/java.compiler/share/classes/javax/lang/model/util/SimpleTypeVisitor7.java src/java.compiler/share/classes/javax/lang/model/util/SimpleTypeVisitor8.java src/java.compiler/share/classes/javax/lang/model/util/SimpleTypeVisitor9.java src/java.compiler/share/classes/javax/lang/model/util/TypeKindVisitor14.java src/java.compiler/share/classes/javax/lang/model/util/TypeKindVisitor6.java src/java.compiler/share/classes/javax/lang/model/util/TypeKindVisitor7.java src/java.compiler/share/classes/javax/lang/model/util/TypeKindVisitor8.java src/java.compiler/share/classes/javax/lang/model/util/TypeKindVisitor9.java
diffstat 48 files changed, 410 insertions(+), 973 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.compiler/share/classes/javax/lang/model/element/AnnotationValueVisitor.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/element/AnnotationValueVisitor.java	Sat Mar 14 09:53:43 2020 -0700
@@ -48,33 +48,34 @@
  * is {@code null}; see documentation of the implementing class for
  * details.
  *
- * <p> <b>WARNING:</b> It is possible that methods will be added to
- * this interface to accommodate new, currently unknown, language
+ * @apiNote
+ * <strong>WARNING:</strong> 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&trade; programming
- * language.  Therefore, 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
- * abstract visitor class that implements this interface.  However, an
- * API should generally use this visitor interface as the type for
- * parameters, return type, etc. rather than one of the abstract
- * classes.
+ * language.
  *
- * <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.
+ * Such additions have already occurred in another visitor interface in
+ * this package to support language features added after this API was
+ * introduced.
  *
- * @apiNote
+ * 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 abstract visitor class that
+ * implements this interface.  However, an API should generally use
+ * this visitor interface as the type for parameters, return type,
+ * etc. rather than one of the abstract classes.
  *
- * There are several families of classes implementing this visitor
+ * <p>Methods to accommodate new language constructs are expected to
+ * be added as default methods to provide strong source compatibility,
+ * as done for {@link ElementVisitor#visitModule visitModule} in
+ * {@code ElementVisitor}. The implementations of the default methods
+ * in this interface will in turn call {@link visitUnknown
+ * visitUnknown}, behavior that will be overridden in concrete
+ * visitors supporting the source version with the new language
+ * construct.
+ *
+ * <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
--- a/src/java.compiler/share/classes/javax/lang/model/element/ElementVisitor.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/element/ElementVisitor.java	Sat Mar 14 09:53:43 2020 -0700
@@ -40,33 +40,32 @@
  * is {@code null}; see documentation of the implementing class for
  * details.
  *
- * <p> <b>WARNING:</b> It is possible that methods will be added to
- * this interface to accommodate new, currently unknown, language
+ * @apiNote
+ * <strong>WARNING:</strong> 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&trade; programming
- * language.  Therefore, 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
- * abstract visitor class that implements this interface.  However, an
- * API should generally use this visitor interface as the type for
- * parameters, return type, etc. rather than one of the abstract
- * classes.
+ * language.
  *
- * <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.
+ * Such additions have already occurred to support language features
+ * added after this API was introduced.
  *
- * @apiNote
+ * 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 abstract visitor class that
+ * implements this interface.  However, an API should generally use
+ * this visitor interface as the type for parameters, return type,
+ * etc. rather than one of the abstract classes.
  *
- * There are several families of classes implementing this visitor
+ * <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.
+ *
+ * <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
--- a/src/java.compiler/share/classes/javax/lang/model/type/TypeVisitor.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/type/TypeVisitor.java	Sat Mar 14 09:53:43 2020 -0700
@@ -41,33 +41,31 @@
  * is {@code null}; see documentation of the implementing class for
  * details.
  *
- * <p> <b>WARNING:</b> It is possible that methods will be added to
- * this interface to accommodate new, currently unknown, language
+ * @apiNote
+ * <strong>WARNING:</strong> 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&trade; programming
- * language.  Therefore, 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
- * abstract visitor class that implements this interface.  However, an
- * API should generally use this visitor interface as the type for
- * parameters, return type, etc. rather than one of the abstract
- * classes.
+ * language.
  *
- * <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.
+ * Such additions have already occurred to support language features
+ * added after this API was introduced.
  *
- * @apiNote
+ * 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 abstract visitor class that
+ * implements this interface.  However, an API should generally use
+ * this visitor interface as the type for parameters, return type,
+ * etc. rather than one of the abstract classes.
  *
- * There are several families of classes implementing this visitor
+ * <p>Methods to accommodate new language constructs are expected to
+ * be added as default methods to provide strong source
+ * compatibility. 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.
+ *
+ * <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
--- a/src/java.compiler/share/classes/javax/lang/model/util/AbstractAnnotationValueVisitor14.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/AbstractAnnotationValueVisitor14.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2019, 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
@@ -33,26 +33,11 @@
  * A skeletal visitor for annotation values with default behavior
  * appropriate for source version {@link SourceVersion#RELEASE_14 RELEASE_14}.
  *
- * <p> <b>WARNING:</b> The {@code AnnotationValueVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new abstract annotation
- * value 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.
- *
  * @param <R> the return type of this visitor's methods
  * @param <P> the type of the additional parameter to this visitor's methods.
  *
+ * @see <a href="AbstractAnnotationValueVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see AbstractAnnotationValueVisitor6
  * @see AbstractAnnotationValueVisitor7
  * @see AbstractAnnotationValueVisitor8
--- a/src/java.compiler/share/classes/javax/lang/model/util/AbstractAnnotationValueVisitor6.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/AbstractAnnotationValueVisitor6.java	Sat Mar 14 09:53:43 2020 -0700
@@ -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
@@ -37,22 +37,25 @@
  * appropriate for the {@link SourceVersion#RELEASE_6 RELEASE_6}
  * source version.
  *
- * <p> <b>WARNING:</b> The {@code AnnotationValueVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * methods with names beginning with {@code "visit"}.
+ * @apiNote
+ * <p id=note_for_subclasses><strong>WARNING:</strong> The {@code
+ * AnnotationValueVisitor} 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&trade; programming language.  Therefore, methods whose
+ * names begin with {@code "visit"} may be added to this class in the
+ * future; to avoid incompatibilities, classes and subclasses which
+ * extend this class should not declare any instance methods with
+ * names beginning with {@code "visit"}.</p>
  *
  * <p>When such a new visit method is added, the default
- * implementation in this class will be to call the {@link
- * #visitUnknown visitUnknown} method.  A new abstract annotation
- * value 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.
+ * implementation in this class will be to directly or indirectly call
+ * the {@link #visitUnknown visitUnknown} method.  A new abstract
+ * annotation value 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
+ * 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
  * @param <P> the type of the additional parameter to this visitor's methods.
--- a/src/java.compiler/share/classes/javax/lang/model/util/AbstractAnnotationValueVisitor7.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/AbstractAnnotationValueVisitor7.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 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
@@ -34,26 +34,11 @@
  * appropriate for the {@link SourceVersion#RELEASE_7 RELEASE_7}
  * source version.
  *
- * <p> <b>WARNING:</b> The {@code AnnotationValueVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new abstract annotation
- * value 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.
- *
  * @param <R> the return type of this visitor's methods
  * @param <P> the type of the additional parameter to this visitor's methods.
  *
+ * @see <a href="AbstractAnnotationValueVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see AbstractAnnotationValueVisitor6
  * @see AbstractAnnotationValueVisitor8
  * @see AbstractAnnotationValueVisitor9
--- a/src/java.compiler/share/classes/javax/lang/model/util/AbstractAnnotationValueVisitor8.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/AbstractAnnotationValueVisitor8.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 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
@@ -34,26 +34,11 @@
  * appropriate for the {@link SourceVersion#RELEASE_8 RELEASE_8}
  * source version.
  *
- * <p> <b>WARNING:</b> The {@code AnnotationValueVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new abstract annotation
- * value 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.
- *
  * @param <R> the return type of this visitor's methods
  * @param <P> the type of the additional parameter to this visitor's methods.
  *
+ * @see <a href="AbstractAnnotationValueVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see AbstractAnnotationValueVisitor6
  * @see AbstractAnnotationValueVisitor7
  * @see AbstractAnnotationValueVisitor9
--- a/src/java.compiler/share/classes/javax/lang/model/util/AbstractAnnotationValueVisitor9.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/AbstractAnnotationValueVisitor9.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 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
@@ -34,26 +34,11 @@
  * appropriate for source versions {@link SourceVersion#RELEASE_9
  * RELEASE_9} through {@link SourceVersion#RELEASE_14 RELEASE_14}.
  *
- * <p> <b>WARNING:</b> The {@code AnnotationValueVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new abstract annotation
- * value 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.
- *
  * @param <R> the return type of this visitor's methods
  * @param <P> the type of the additional parameter to this visitor's methods.
  *
+ * @see <a href="AbstractAnnotationValueVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see AbstractAnnotationValueVisitor6
  * @see AbstractAnnotationValueVisitor7
  * @see AbstractAnnotationValueVisitor8
--- a/src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor14.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor14.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2019, 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
@@ -42,29 +42,14 @@
  * appropriate for the {@link SourceVersion#RELEASE_14 RELEASE_14}
  * source version.
  *
- * <p> <b>WARNING:</b> 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #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.
- *
  * @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
  *            methods.  Use {@code Void} for visitors that do not need an
  *            additional parameter.
  *
+ * @see <a href="AbstractElementVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see AbstractElementVisitor6
  * @see AbstractElementVisitor7
  * @see AbstractElementVisitor8
--- a/src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor6.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor6.java	Sat Mar 14 09:53:43 2020 -0700
@@ -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
@@ -36,22 +36,25 @@
  * appropriate for the {@link SourceVersion#RELEASE_6 RELEASE_6}
  * source version.
  *
- * <p> <b>WARNING:</b> 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * methods with names beginning with {@code "visit"}.
+ * @apiNote
+ * <p id=note_for_subclasses><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&trade; programming language.  Therefore, methods whose names
+ * begin with {@code "visit"} may be added to this class in the
+ * future; to avoid incompatibilities, classes and subclasses which
+ * extend this class should not declare any instance methods with
+ * names beginning with {@code "visit"}.</p>
  *
  * <p>When such a new visit method is added, the default
- * implementation in this class will be to 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.
+ * 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 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.
--- a/src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor7.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor7.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 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
@@ -35,29 +35,14 @@
  * appropriate for the {@link SourceVersion#RELEASE_7 RELEASE_7}
  * source version.
  *
- * <p> <b>WARNING:</b> 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #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.
- *
  * @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
  *            methods.  Use {@code Void} for visitors that do not need an
  *            additional parameter.
  *
+ * @see <a href="AbstractElementVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see AbstractElementVisitor6
  * @see AbstractElementVisitor8
  * @see AbstractElementVisitor9
--- a/src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor8.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor8.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 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
@@ -35,29 +35,14 @@
  * appropriate for the {@link SourceVersion#RELEASE_8 RELEASE_8}
  * source version.
  *
- * <p> <b>WARNING:</b> 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #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.
- *
  * @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
  *            methods.  Use {@code Void} for visitors that do not need an
  *            additional parameter.
  *
+ * @see <a href="AbstractElementVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see AbstractElementVisitor6
  * @see AbstractElementVisitor7
  * @see AbstractElementVisitor9
--- a/src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor9.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor9.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 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
@@ -36,29 +36,14 @@
  * appropriate for source versions {@link SourceVersion#RELEASE_9
  * RELEASE_9} through {@link SourceVersion#RELEASE_14 RELEASE_14}.
  *
- * <p> <b>WARNING:</b> 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #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.
- *
  * @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
  *            methods.  Use {@code Void} for visitors that do not need an
  *            additional parameter.
  *
+ * @see <a href="AbstractElementVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see AbstractElementVisitor6
  * @see AbstractElementVisitor7
  * @see AbstractElementVisitor8
--- a/src/java.compiler/share/classes/javax/lang/model/util/AbstractTypeVisitor14.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/AbstractTypeVisitor14.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2019, 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
@@ -33,29 +33,14 @@
  * A skeletal visitor of types with default behavior appropriate for the
  * {@link SourceVersion#RELEASE_14 RELEASE_14} source version.
  *
- * <p> <b>WARNING:</b> The {@code TypeVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new abstract type 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.
- *
  * @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
  *            methods.  Use {@code Void} for visitors that do not need an
  *            additional parameter.
  *
+ * @see <a href="AbstractTypeVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see AbstractTypeVisitor6
  * @see AbstractTypeVisitor7
  * @see AbstractTypeVisitor8
--- a/src/java.compiler/share/classes/javax/lang/model/util/AbstractTypeVisitor6.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/AbstractTypeVisitor6.java	Sat Mar 14 09:53:43 2020 -0700
@@ -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
@@ -35,22 +35,25 @@
  * the {@link javax.lang.model.SourceVersion#RELEASE_6 RELEASE_6}
  * source version.
  *
- * <p> <b>WARNING:</b> The {@code TypeVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * methods with names beginning with {@code "visit"}.
+ * @apiNote
+ * <p id=note_for_subclasses><strong>WARNING:</strong> The {@code
+ * TypeVisitor} 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&trade;
+ * programming language.  Therefore, methods whose names begin with
+ * {@code "visit"} may be added to this class in the future; to avoid
+ * incompatibilities, classes and subclasses which extend this class
+ * should not declare any instance 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
- * #visitUnknown visitUnknown} method.  A new abstract type 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.
+ * implementation in this class will be to directly or indirectly call
+ * the {@link #visitUnknown visitUnknown} method.  A new abstract type
+ * 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 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.
--- a/src/java.compiler/share/classes/javax/lang/model/util/AbstractTypeVisitor7.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/AbstractTypeVisitor7.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 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
@@ -35,29 +35,14 @@
  * the {@link javax.lang.model.SourceVersion#RELEASE_7 RELEASE_7}
  * source version.
  *
- * <p> <b>WARNING:</b> The {@code TypeVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new abstract type 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.
- *
  * @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
  *            methods.  Use {@code Void} for visitors that do not need an
  *            additional parameter.
  *
+ * @see <a href="AbstractTypeVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see AbstractTypeVisitor6
  * @see AbstractTypeVisitor8
  * @see AbstractTypeVisitor9
--- a/src/java.compiler/share/classes/javax/lang/model/util/AbstractTypeVisitor8.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/AbstractTypeVisitor8.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 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
@@ -35,29 +35,14 @@
  * the {@link javax.lang.model.SourceVersion#RELEASE_8 RELEASE_8}
  * source version.
  *
- * <p> <b>WARNING:</b> The {@code TypeVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new abstract type 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.
- *
  * @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
  *            methods.  Use {@code Void} for visitors that do not need an
  *            additional parameter.
  *
+ * @see <a href="AbstractTypeVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see AbstractTypeVisitor6
  * @see AbstractTypeVisitor7
  * @see AbstractTypeVisitor9
--- a/src/java.compiler/share/classes/javax/lang/model/util/AbstractTypeVisitor9.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/AbstractTypeVisitor9.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 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
@@ -35,29 +35,14 @@
  * source versions {@link SourceVersion#RELEASE_9 RELEASE_9} through
  * {@link SourceVersion#RELEASE_14 RELEASE_14}.
  *
- * <p> <b>WARNING:</b> The {@code TypeVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new abstract type 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.
- *
  * @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
  *            methods.  Use {@code Void} for visitors that do not need an
  *            additional parameter.
  *
+ * @see <a href="AbstractTypeVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see AbstractTypeVisitor6
  * @see AbstractTypeVisitor7
  * @see AbstractTypeVisitor8
--- a/src/java.compiler/share/classes/javax/lang/model/util/ElementKindVisitor14.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/ElementKindVisitor14.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2019, 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
@@ -50,29 +50,9 @@
  * call {@link #defaultAction defaultAction}, passing their arguments
  * to {@code defaultAction}'s corresponding parameters.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
- *
- * <p> <b>WARNING:</b> The {@code ElementVisitor} interface
- * implemented by this class may have methods added to it or the
- * {@code ElementKind} {@code enum} used in this case may have
- * constants added to it in the future to accommodate new, currently
- * unknown, language structures added to future versions of the
- * Java&trade; programming language.  Therefore, methods whose names
- * begin with {@code "visit"} may be added to this class in the
- * future; to avoid incompatibilities, classes which extend this class
- * should not declare any instance 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
- * #visitUnknown visitUnknown} method.  A new abstract element kind
- * 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.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
  * @param <R> the return type of this visitor's methods.  Use {@link
  *            Void} for visitors that do not need to return results.
@@ -80,6 +60,8 @@
  *            methods.  Use {@code Void} for visitors that do not need an
  *            additional parameter.
  *
+ * @see <a href="ElementKindVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see ElementKindVisitor6
  * @see ElementKindVisitor7
  * @see ElementKindVisitor8
--- a/src/java.compiler/share/classes/javax/lang/model/util/ElementKindVisitor6.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/ElementKindVisitor6.java	Sat Mar 14 09:53:43 2020 -0700
@@ -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
@@ -43,29 +43,29 @@
  * call {@link #defaultAction defaultAction}, passing their arguments
  * to {@code defaultAction}'s corresponding parameters.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
- * <p> <b>WARNING:</b> The {@code ElementVisitor} interface
- * implemented by this class may have methods added to it or the
- * {@code ElementKind} {@code enum} used in this case may have
- * constants added to it in the future to accommodate new, currently
- * unknown, language structures added to future versions of the
- * Java&trade; programming language.  Therefore, methods whose names
- * begin with {@code "visit"} may be added to this class in the
- * future; to avoid incompatibilities, classes which extend this class
- * should not declare any instance methods with names beginning with
- * {@code "visit"}.
+ * <p id=note_for_subclasses><strong>WARNING:</strong> The {@code
+ * ElementVisitor} interface implemented by this class may have
+ * methods added to it or the {@link ElementKind ElementKind enum}
+ * used in this class may have constants added to it in the future to
+ * accommodate new, currently unknown, language structures added to
+ * future versions of the Java&trade; programming language.
+ * Therefore, methods whose names begin with {@code "visit"} may be
+ * added to this class in the future; to avoid incompatibilities,
+ * classes and subclasses which extend this class should not declare
+ * any instance methods with names beginning with {@code "visit"}.</p>
  *
  * <p>When such a new visit method is added, the default
- * implementation in this class will be to call the {@link
- * #visitUnknown visitUnknown} method.  A new abstract element kind
- * 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.
+ * implementation in this class will be to directly or indirectly call
+ * the {@link #visitUnknown visitUnknown} method.  A new abstract
+ * element kind 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 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.
--- a/src/java.compiler/share/classes/javax/lang/model/util/ElementKindVisitor7.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/ElementKindVisitor7.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 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
@@ -41,29 +41,9 @@
  * call {@link #defaultAction defaultAction}, passing their arguments
  * to {@code defaultAction}'s corresponding parameters.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
- *
- * <p> <b>WARNING:</b> The {@code ElementVisitor} interface
- * implemented by this class may have methods added to it or the
- * {@code ElementKind} {@code enum} used in this case may have
- * constants added to it in the future to accommodate new, currently
- * unknown, language structures added to future versions of the
- * Java&trade; programming language.  Therefore, methods whose names
- * begin with {@code "visit"} may be added to this class in the
- * future; to avoid incompatibilities, classes which extend this class
- * should not declare any instance 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
- * #visitUnknown visitUnknown} method.  A new abstract element kind
- * 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.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
  * @param <R> the return type of this visitor's methods.  Use {@link
  *            Void} for visitors that do not need to return results.
@@ -71,6 +51,8 @@
  *            methods.  Use {@code Void} for visitors that do not need an
  *            additional parameter.
  *
+ * @see <a href="ElementKindVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see ElementKindVisitor6
  * @see ElementKindVisitor8
  * @see ElementKindVisitor9
--- a/src/java.compiler/share/classes/javax/lang/model/util/ElementKindVisitor8.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/ElementKindVisitor8.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 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
@@ -41,29 +41,9 @@
  * call {@link #defaultAction defaultAction}, passing their arguments
  * to {@code defaultAction}'s corresponding parameters.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
- *
- * <p> <b>WARNING:</b> The {@code ElementVisitor} interface
- * implemented by this class may have methods added to it or the
- * {@code ElementKind} {@code enum} used in this case may have
- * constants added to it in the future to accommodate new, currently
- * unknown, language structures added to future versions of the
- * Java&trade; programming language.  Therefore, methods whose names
- * begin with {@code "visit"} may be added to this class in the
- * future; to avoid incompatibilities, classes which extend this class
- * should not declare any instance 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
- * #visitUnknown visitUnknown} method.  A new abstract element kind
- * 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.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
  * @param <R> the return type of this visitor's methods.  Use {@link
  *            Void} for visitors that do not need to return results.
@@ -71,6 +51,8 @@
  *            methods.  Use {@code Void} for visitors that do not need an
  *            additional parameter.
  *
+ * @see <a href="ElementKindVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see ElementKindVisitor6
  * @see ElementKindVisitor7
  * @see ElementKindVisitor9
--- a/src/java.compiler/share/classes/javax/lang/model/util/ElementKindVisitor9.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/ElementKindVisitor9.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 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
@@ -44,29 +44,9 @@
  * call {@link #defaultAction defaultAction}, passing their arguments
  * to {@code defaultAction}'s corresponding parameters.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
- *
- * <p> <b>WARNING:</b> The {@code ElementVisitor} interface
- * implemented by this class may have methods added to it or the
- * {@code ElementKind} {@code enum} used in this case may have
- * constants added to it in the future to accommodate new, currently
- * unknown, language structures added to future versions of the
- * Java&trade; programming language.  Therefore, methods whose names
- * begin with {@code "visit"} may be added to this class in the
- * future; to avoid incompatibilities, classes which extend this class
- * should not declare any instance 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
- * #visitUnknown visitUnknown} method.  A new abstract element kind
- * 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.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
  * @param <R> the return type of this visitor's methods.  Use {@link
  *            Void} for visitors that do not need to return results.
@@ -74,6 +54,8 @@
  *            methods.  Use {@code Void} for visitors that do not need an
  *            additional parameter.
  *
+ * @see <a href="ElementKindVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see ElementKindVisitor6
  * @see ElementKindVisitor7
  * @see ElementKindVisitor8
--- a/src/java.compiler/share/classes/javax/lang/model/util/ElementScanner14.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/ElementScanner14.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2019, 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
@@ -66,27 +66,9 @@
  * calling <code>super.visit<i>Xyz</i></code>, an overriding visit method
  * should call {@code scan} with the elements in the desired order.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
- *
- * <p> <b>WARNING:</b> 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new element scanner 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.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
  * @param <R> the return type of this visitor's methods.  Use {@link
  *            Void} for visitors that do not need to return results.
@@ -94,6 +76,7 @@
  *            methods.  Use {@code Void} for visitors that do not need an
  *            additional parameter.
  *
+ * @see <a href="ElementScanner6.html#note_for_subclasses"><strong>Compatibility note for subclasses</strong></a>
  * @see ElementScanner6
  * @see ElementScanner7
  * @see ElementScanner8
--- a/src/java.compiler/share/classes/javax/lang/model/util/ElementScanner6.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/ElementScanner6.java	Sat Mar 14 09:53:43 2020 -0700
@@ -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
@@ -56,27 +56,26 @@
  * calling <code>super.visit<i>Xyz</i></code>, an overriding visit method
  * should call {@code scan} with the elements in the desired order.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
- * <p> <b>WARNING:</b> The {@code ElementVisitor} interface
+ * <p id=note_for_subclasses><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&trade; programming language.
  * Therefore, methods whose names begin with {@code "visit"} may be
  * added to this class in the future; to avoid incompatibilities,
  * classes which extend this class should not declare any instance
- * methods with names beginning with {@code "visit"}.
+ * methods with names beginning with {@code "visit"}.</p>
  *
  * <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 element scanner 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.
--- a/src/java.compiler/share/classes/javax/lang/model/util/ElementScanner7.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/ElementScanner7.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 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
@@ -56,27 +56,9 @@
  * calling <code>super.visit<i>Xyz</i></code>, an overriding visit method
  * should call {@code scan} with the elements in the desired order.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
- *
- * <p> <b>WARNING:</b> 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new element scanner 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.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
  * @param <R> the return type of this visitor's methods.  Use {@link
  *            Void} for visitors that do not need to return results.
@@ -84,6 +66,7 @@
  *            methods.  Use {@code Void} for visitors that do not need an
  *            additional parameter.
  *
+ * @see <a href="ElementScanner6.html#note_for_subclasses"><strong>Compatibility note for subclasses</strong></a>
  * @see ElementScanner6
  * @see ElementScanner8
  * @see ElementScanner9
--- a/src/java.compiler/share/classes/javax/lang/model/util/ElementScanner8.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/ElementScanner8.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 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
@@ -56,27 +56,9 @@
  * calling <code>super.visit<i>Xyz</i></code>, an overriding visit method
  * should call {@code scan} with the elements in the desired order.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
- *
- * <p> <b>WARNING:</b> 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new element scanner 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.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
  * @param <R> the return type of this visitor's methods.  Use {@link
  *            Void} for visitors that do not need to return results.
@@ -84,6 +66,7 @@
  *            methods.  Use {@code Void} for visitors that do not need an
  *            additional parameter.
  *
+ * @see <a href="ElementScanner6.html#note_for_subclasses"><strong>Compatibility note for subclasses</strong></a>
  * @see ElementScanner6
  * @see ElementScanner7
  * @see ElementScanner9
--- a/src/java.compiler/share/classes/javax/lang/model/util/ElementScanner9.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/ElementScanner9.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 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
@@ -58,27 +58,9 @@
  * calling <code>super.visit<i>Xyz</i></code>, an overriding visit method
  * should call {@code scan} with the elements in the desired order.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
- *
- * <p> <b>WARNING:</b> 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new element scanner 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.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
  * @param <R> the return type of this visitor's methods.  Use {@link
  *            Void} for visitors that do not need to return results.
@@ -86,6 +68,7 @@
  *            methods.  Use {@code Void} for visitors that do not need an
  *            additional parameter.
  *
+ * @see <a href="ElementScanner6.html#note_for_subclasses"><strong>Compatibility note for subclasses</strong></a>
  * @see ElementScanner6
  * @see ElementScanner7
  * @see ElementScanner8
--- a/src/java.compiler/share/classes/javax/lang/model/util/SimpleAnnotationValueVisitor14.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/SimpleAnnotationValueVisitor14.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2019, 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
@@ -37,31 +37,15 @@
  * defaultAction} passing their arguments to {@code defaultAction}'s
  * corresponding parameters.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
- *
- * <p> <b>WARNING:</b> The {@code AnnotationValueVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new simple annotation
- * value 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.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
  * @param <R> the return type of this visitor's methods
  * @param <P> the type of the additional parameter to this visitor's methods.
  *
+ * @see <a href="SimpleAnnotationValueVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see SimpleAnnotationValueVisitor6
  * @see SimpleAnnotationValueVisitor7
  * @see SimpleAnnotationValueVisitor8
--- a/src/java.compiler/share/classes/javax/lang/model/util/SimpleAnnotationValueVisitor6.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/SimpleAnnotationValueVisitor6.java	Sat Mar 14 09:53:43 2020 -0700
@@ -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
@@ -41,27 +41,28 @@
  * #defaultAction} passing their arguments to {@code defaultAction}'s
  * corresponding parameters.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
- * <p> <b>WARNING:</b> The {@code AnnotationValueVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * methods with names beginning with {@code "visit"}.
+ * <p id=note_for_subclasses><strong>WARNING:</strong> The {@code
+ * AnnotationValueVisitor} 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&trade; programming language.  Therefore, methods whose
+ * names begin with {@code "visit"} may be added to this class in the
+ * future; to avoid incompatibilities, classes and subclasses which
+ * extend this class should not declare any instance methods with
+ * names beginning with {@code "visit"}.</p>
  *
  * <p>When such a new visit method is added, the default
- * implementation in this class will be to call the {@link
- * #visitUnknown visitUnknown} method.  A new simple annotation
- * value 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.
+ * implementation in this class will be to directly or indirectly call
+ * the {@link #visitUnknown visitUnknown} method.  A new simple
+ * annotation value 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
+ * 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
  * @param <P> the type of the additional parameter to this visitor's methods.
--- a/src/java.compiler/share/classes/javax/lang/model/util/SimpleAnnotationValueVisitor7.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/SimpleAnnotationValueVisitor7.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 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
@@ -36,31 +36,15 @@
  * defaultAction} passing their arguments to {@code defaultAction}'s
  * corresponding parameters.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
- *
- * <p> <b>WARNING:</b> The {@code AnnotationValueVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new simple annotation
- * value 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.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
  * @param <R> the return type of this visitor's methods
  * @param <P> the type of the additional parameter to this visitor's methods.
  *
+ * @see <a href="SimpleAnnotationValueVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see SimpleAnnotationValueVisitor6
  * @see SimpleAnnotationValueVisitor8
  * @see SimpleAnnotationValueVisitor9
--- a/src/java.compiler/share/classes/javax/lang/model/util/SimpleAnnotationValueVisitor8.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/SimpleAnnotationValueVisitor8.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 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
@@ -36,31 +36,15 @@
  * defaultAction} passing their arguments to {@code defaultAction}'s
  * corresponding parameters.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
- *
- * <p> <b>WARNING:</b> The {@code AnnotationValueVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new simple annotation
- * value 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.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
  * @param <R> the return type of this visitor's methods
  * @param <P> the type of the additional parameter to this visitor's methods.
  *
+ * @see <a href="SimpleAnnotationValueVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see SimpleAnnotationValueVisitor6
  * @see SimpleAnnotationValueVisitor7
  * @see SimpleAnnotationValueVisitor8
--- a/src/java.compiler/share/classes/javax/lang/model/util/SimpleAnnotationValueVisitor9.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/SimpleAnnotationValueVisitor9.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 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
@@ -38,31 +38,15 @@
  * defaultAction} passing their arguments to {@code defaultAction}'s
  * corresponding parameters.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
- *
- * <p> <b>WARNING:</b> The {@code AnnotationValueVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new simple annotation
- * value 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.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
  * @param <R> the return type of this visitor's methods
  * @param <P> the type of the additional parameter to this visitor's methods.
  *
+ * @see <a href="SimpleAnnotationValueVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see SimpleAnnotationValueVisitor6
  * @see SimpleAnnotationValueVisitor7
  * @see SimpleAnnotationValueVisitor8
--- a/src/java.compiler/share/classes/javax/lang/model/util/SimpleElementVisitor14.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/SimpleElementVisitor14.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2019, 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
@@ -47,33 +47,17 @@
  * passing their arguments to {@code defaultAction}'s corresponding
  * parameters.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
- *
- * <p> <b>WARNING:</b> 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new simple 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.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
  * @param <R> the return type of this visitor's methods.  Use {@code Void}
  *             for visitors that do not need to return results.
  * @param <P> the type of the additional parameter to this visitor's methods.  Use {@code Void}
  *              for visitors that do not need an additional parameter.
  *
+ * @see <a href="SimpleElementVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see SimpleElementVisitor6
  * @see SimpleElementVisitor7
  * @see SimpleElementVisitor8
--- a/src/java.compiler/share/classes/javax/lang/model/util/SimpleElementVisitor6.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/SimpleElementVisitor6.java	Sat Mar 14 09:53:43 2020 -0700
@@ -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
@@ -43,27 +43,29 @@
  * For constructs introduced in {@code RELEASE_7} and later, {@code
  * visitUnknown} is called instead.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
  *
- * <p> <b>WARNING:</b> 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * methods with names beginning with {@code "visit"}.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
+ *
+ * <p id=note_for_subclasses><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&trade; programming language.  Therefore, methods whose names
+ * begin with {@code "visit"} may be added to this class in the
+ * future; to avoid incompatibilities, classes and subclasses which
+ * extend this class should not declare any instance methods with
+ * names beginning with {@code "visit"}.</p>
  *
  * <p>When such a new visit method is added, the default
- * implementation in this class will be to call the {@link
- * #visitUnknown visitUnknown} method.  A new simple 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.
+ * implementation in this class will be to directly or indirectly call
+ * the {@link #visitUnknown visitUnknown} method.  A new simple
+ * 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 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 {@code Void}
  *             for visitors that do not need to return results.
--- a/src/java.compiler/share/classes/javax/lang/model/util/SimpleElementVisitor7.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/SimpleElementVisitor7.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 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
@@ -40,33 +40,17 @@
  * passing their arguments to {@code defaultAction}'s corresponding
  * parameters.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
- *
- * <p> <b>WARNING:</b> 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new simple 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.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
  * @param <R> the return type of this visitor's methods.  Use {@code Void}
  *             for visitors that do not need to return results.
  * @param <P> the type of the additional parameter to this visitor's methods.  Use {@code Void}
  *              for visitors that do not need an additional parameter.
  *
+ * @see <a href="SimpleElementVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see SimpleElementVisitor6
  * @see SimpleElementVisitor8
  * @see SimpleElementVisitor9
--- a/src/java.compiler/share/classes/javax/lang/model/util/SimpleElementVisitor8.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/SimpleElementVisitor8.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 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
@@ -39,33 +39,17 @@
  * passing their arguments to {@code defaultAction}'s corresponding
  * parameters.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
- *
- * <p> <b>WARNING:</b> 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new simple 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.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
  * @param <R> the return type of this visitor's methods.  Use {@code Void}
  *             for visitors that do not need to return results.
  * @param <P> the type of the additional parameter to this visitor's methods.  Use {@code Void}
  *              for visitors that do not need an additional parameter.
  *
+ * @see <a href="SimpleElementVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see SimpleElementVisitor6
  * @see SimpleElementVisitor7
  * @see SimpleElementVisitor9
--- a/src/java.compiler/share/classes/javax/lang/model/util/SimpleElementVisitor9.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/SimpleElementVisitor9.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 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
@@ -40,33 +40,17 @@
  * passing their arguments to {@code defaultAction}'s corresponding
  * parameters.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
- *
- * <p> <b>WARNING:</b> 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new simple 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.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
  * @param <R> the return type of this visitor's methods.  Use {@code Void}
  *             for visitors that do not need to return results.
  * @param <P> the type of the additional parameter to this visitor's methods.  Use {@code Void}
  *              for visitors that do not need an additional parameter.
  *
+ * @see <a href="SimpleElementVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see SimpleElementVisitor6
  * @see SimpleElementVisitor7
  * @see SimpleElementVisitor8
--- a/src/java.compiler/share/classes/javax/lang/model/util/SimpleTypeVisitor14.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/SimpleTypeVisitor14.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2019, 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
@@ -38,27 +38,9 @@
  * passing their arguments to {@code defaultAction}'s corresponding
  * parameters.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
- *
- * <p> <b>WARNING:</b> The {@code TypeVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new simple type 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.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
  * @param <R> the return type of this visitor's methods.  Use {@link
  *            Void} for visitors that do not need to return results.
@@ -66,6 +48,8 @@
  *            methods.  Use {@code Void} for visitors that do not need an
  *            additional parameter.
  *
+ * @see <a href="SimpleTypeVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see SimpleTypeVisitor6
  * @see SimpleTypeVisitor7
  * @see SimpleTypeVisitor8
--- a/src/java.compiler/share/classes/javax/lang/model/util/SimpleTypeVisitor6.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/SimpleTypeVisitor6.java	Sat Mar 14 09:53:43 2020 -0700
@@ -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
@@ -42,27 +42,29 @@
  * For constructs introduced in {@code RELEASE_7} and later, {@code
  * visitUnknown} is called instead.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
  *
- * <p> <b>WARNING:</b> The {@code TypeVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * methods with names beginning with {@code "visit"}.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
+ *
+ * <p id=note_for_subclasses><strong>WARNING:</strong> The {@code
+ * TypeVisitor} 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&trade;
+ * programming language.  Therefore, methods whose names begin with
+ * {@code "visit"} may be added to this class in the future; to avoid
+ * incompatibilities, classes and subclasses which extend this class
+ * should not declare any instance methods with names beginning with
+ * {@code "visit"}.</p>
  *
  * <p>When such a new visit method is added, the default
- * implementation in this class will be to call the {@link
- * #visitUnknown visitUnknown} method.  A new simple type 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.
+ * implementation in this class will be to directly or indirectly call
+ * the {@link #visitUnknown visitUnknown} method.  A new simple type
+ * 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 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.
--- a/src/java.compiler/share/classes/javax/lang/model/util/SimpleTypeVisitor7.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/SimpleTypeVisitor7.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 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
@@ -39,27 +39,9 @@
  * passing their arguments to {@code defaultAction}'s corresponding
  * parameters.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
- *
- * <p> <b>WARNING:</b> The {@code TypeVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new simple type 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.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
  * @param <R> the return type of this visitor's methods.  Use {@link
  *            Void} for visitors that do not need to return results.
@@ -67,6 +49,8 @@
  *            methods.  Use {@code Void} for visitors that do not need an
  *            additional parameter.
  *
+ * @see <a href="SimpleTypeVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see SimpleTypeVisitor6
  * @see SimpleTypeVisitor8
  * @see SimpleTypeVisitor9
--- a/src/java.compiler/share/classes/javax/lang/model/util/SimpleTypeVisitor8.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/SimpleTypeVisitor8.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 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
@@ -39,27 +39,9 @@
  * passing their arguments to {@code defaultAction}'s corresponding
  * parameters.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
- *
- * <p> <b>WARNING:</b> The {@code TypeVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new simple type 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.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
  * @param <R> the return type of this visitor's methods.  Use {@link
  *            Void} for visitors that do not need to return results.
@@ -67,6 +49,8 @@
  *            methods.  Use {@code Void} for visitors that do not need an
  *            additional parameter.
  *
+ * @see <a href="SimpleTypeVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see SimpleTypeVisitor6
  * @see SimpleTypeVisitor7
  * @see SimpleTypeVisitor9
--- a/src/java.compiler/share/classes/javax/lang/model/util/SimpleTypeVisitor9.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/SimpleTypeVisitor9.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 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
@@ -40,27 +40,9 @@
  * passing their arguments to {@code defaultAction}'s corresponding
  * parameters.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
- *
- * <p> <b>WARNING:</b> The {@code TypeVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new simple type 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.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
  * @param <R> the return type of this visitor's methods.  Use {@link
  *            Void} for visitors that do not need to return results.
@@ -68,6 +50,8 @@
  *            methods.  Use {@code Void} for visitors that do not need an
  *            additional parameter.
  *
+ * @see <a href="SimpleTypeVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see SimpleTypeVisitor6
  * @see SimpleTypeVisitor7
  * @see SimpleTypeVisitor8
--- a/src/java.compiler/share/classes/javax/lang/model/util/TypeKindVisitor14.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/TypeKindVisitor14.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2019, 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
@@ -43,27 +43,9 @@
  * call {@link #defaultAction defaultAction}, passing their arguments
  * to {@code defaultAction}'s corresponding parameters.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
- *
- * <p> <b>WARNING:</b> The {@code TypeVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new type kind 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.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
  * @param <R> the return type of this visitor's methods.  Use {@link
  *            Void} for visitors that do not need to return results.
@@ -71,6 +53,8 @@
  *            methods.  Use {@code Void} for visitors that do not need an
  *            additional parameter.
  *
+ * @see <a href="TypeKindVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see TypeKindVisitor6
  * @see TypeKindVisitor7
  * @see TypeKindVisitor8
--- a/src/java.compiler/share/classes/javax/lang/model/util/TypeKindVisitor6.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/TypeKindVisitor6.java	Sat Mar 14 09:53:43 2020 -0700
@@ -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
@@ -41,27 +41,29 @@
  * call {@link #defaultAction defaultAction}, passing their arguments
  * to {@code defaultAction}'s corresponding parameters.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
- * <p> <b>WARNING:</b> The {@code TypeVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * methods with names beginning with {@code "visit"}.
+ * <p id=note_for_subclasses><strong>WARNING:</strong> The {@code
+ * TypeVisitor} interface implemented by this class may have methods
+ * added to it or the {@link TypeKind TypeKind enum} used in this
+ * class may have constants added to it in the future to accommodate
+ * new, currently unknown, language structures added to future
+ * versions of the Java&trade; programming language.  Therefore,
+ * methods whose names begin with {@code "visit"} may be added to this
+ * class in the future; to avoid incompatibilities, classes and
+ * subclasses which extend this class should not declare any instance
+ * methods with names beginning with {@code "visit"}.</p>
  *
  * <p>When such a new visit method is added, the default
- * implementation in this class will be to call the {@link
- * #visitUnknown visitUnknown} method.  A new type kind 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.
+ * implementation in this class will be to directly or indirectly call
+ * the {@link #visitUnknown visitUnknown} method.  A new type kind
+ * 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 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.
--- a/src/java.compiler/share/classes/javax/lang/model/util/TypeKindVisitor7.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/TypeKindVisitor7.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 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
@@ -41,27 +41,9 @@
  * call {@link #defaultAction defaultAction}, passing their arguments
  * to {@code defaultAction}'s corresponding parameters.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
- *
- * <p> <b>WARNING:</b> The {@code TypeVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new type kind 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.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
  * @param <R> the return type of this visitor's methods.  Use {@link
  *            Void} for visitors that do not need to return results.
@@ -69,6 +51,8 @@
  *            methods.  Use {@code Void} for visitors that do not need an
  *            additional parameter.
  *
+ * @see <a href="TypeKindVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see TypeKindVisitor6
  * @see TypeKindVisitor8
  * @see TypeKindVisitor9
--- a/src/java.compiler/share/classes/javax/lang/model/util/TypeKindVisitor8.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/TypeKindVisitor8.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 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
@@ -41,27 +41,9 @@
  * call {@link #defaultAction defaultAction}, passing their arguments
  * to {@code defaultAction}'s corresponding parameters.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
- *
- * <p> <b>WARNING:</b> The {@code TypeVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new type kind 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.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
  * @param <R> the return type of this visitor's methods.  Use {@link
  *            Void} for visitors that do not need to return results.
@@ -69,6 +51,8 @@
  *            methods.  Use {@code Void} for visitors that do not need an
  *            additional parameter.
  *
+ * @see <a href="TypeKindVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see TypeKindVisitor6
  * @see TypeKindVisitor7
  * @see TypeKindVisitor9
--- a/src/java.compiler/share/classes/javax/lang/model/util/TypeKindVisitor9.java	Fri Mar 13 15:36:50 2020 -0400
+++ b/src/java.compiler/share/classes/javax/lang/model/util/TypeKindVisitor9.java	Sat Mar 14 09:53:43 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 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
@@ -44,27 +44,9 @@
  * call {@link #defaultAction defaultAction}, passing their arguments
  * to {@code defaultAction}'s corresponding parameters.
  *
- * <p> Methods in this class may be overridden subject to their
- * general contract.  Note that annotating methods in concrete
- * subclasses with {@link java.lang.Override @Override} will help
- * ensure that methods are overridden as intended.
- *
- * <p> <b>WARNING:</b> The {@code TypeVisitor} 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&trade; programming language.
- * Therefore, methods whose names begin with {@code "visit"} may be
- * added to this class in the future; to avoid incompatibilities,
- * classes which extend this class should not declare any instance
- * 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
- * #visitUnknown visitUnknown} method.  A new type kind 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.
+ * @apiNote
+ * Methods in this class may be overridden subject to their general
+ * contract.
  *
  * @param <R> the return type of this visitor's methods.  Use {@link
  *            Void} for visitors that do not need to return results.
@@ -72,6 +54,8 @@
  *            methods.  Use {@code Void} for visitors that do not need an
  *            additional parameter.
  *
+ * @see <a href="TypeKindVisitor6.html#note_for_subclasses">
+ * <strong>Compatibility note for subclasses</strong></a>
  * @see TypeKindVisitor6
  * @see TypeKindVisitor7
  * @see TypeKindVisitor8