OpenJDK / jdk / jdk
changeset 58402:332ee3137fb8
8240130: Improve and update discussion of visitor evolution warnings
Reviewed-by: jjg
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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ + * 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ + * 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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™ 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