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

[Jonathan Gibbons]

Looks good to me.

Consider using a ':' instead of ',' on this line in the first file:

66 * visitUnknown}, behavior that will be overridden in concrete

-- Jon

On 2/26/20 10:00 PM, Joe Darcy wrote:
> Hello,
>
> Please review the documentation changes for
>
>     JDK-8240130: Improve and update discussion of visitor evolution 
> warnings
>     http://cr.openjdk.java.net/~darcy/8240130.0/
>
> Patch below. Some discussion of and rationale for the changes, the 
> original javax.lang.model visitor interfaces and concrete visitor 
> types had various warning about the unusual compatibility policies 
> those types would use. Unlike other post-Java SE 6 era types, it was 
> anticipated methods would be added to interfaces. Prior to default 
> methods in JDK 8, such additions were a highly unusual occurrence for 
> public types in the JDK. After default methods were used commonly in 
> jDK 8, such additions are of less concern. The risk of a true source 
> compatibility is also low for a new "visitFoo" method since it will 
> have a parameter of type Foo, which is new to the release, and thus 
> not have an overloading conflict with a method in an existing visitor 
> outside of the JDK.
>
> The warnings are thus toned down and adjusted to note that the 
> envisioned additions have already occurred for prior language 
> additions. For example, the current policy is only to deprecate the 
> constructors of obsolete visitor classes rather than the whole class. 
> The "directly or indirectly call" visitUnknown is to accurately 
> describe, but not limit to, the current policy of the visitFoo methods 
> in affected concrete visitors calling the visitFoo default method on 
> the *interface*, which in turn calls visitUnknown.
>
> The warning text is pulled into an apiNote to avoid getting 
> inherit-doc-ed for any subclasses. Once the shape of the changes for 
> the interface and visitor classes are agree to, I'll replicated the 
> changes for the other types.
>
> Thanks,
>
> -Joe
>
> --- 
> old/src/java.compiler/share/classes/javax/lang/model/element/ElementVisitor.java 
> 2020-02-26 13:13:00.848880601 -0800
> +++ 
> new/src/java.compiler/share/classes/javax/lang/model/element/ElementVisitor.java 
> 2020-02-26 13:13:00.512880601 -0800
> @@ -40,10 +40,17 @@
>   * is {@code null}; see documentation of the implementing class for
>   * details.
>   *
> - * <p> <b>WARNING:</b> It is possible that methods will be added to
> + * @apiNote
> + *
> + * WARNING: It is possible that methods will be added to
>   * this interface to accommodate new, currently unknown, language
>   * structures added to future versions of the Java™ programming
> - * language.  Therefore, visitor classes directly implementing this
> + * language.
> + *
> + * Such additions have already occurred to support language features
> + * added after this API was introduced.
> + *
> + * Visitor classes directly implementing this
>   * interface may be source incompatible with future versions of the
>   * platform.  To avoid this source incompatibility, visitor
>   * implementations are encouraged to instead extend the appropriate
> @@ -52,21 +59,15 @@
>   * parameters, return type, etc. rather than one of the abstract
>   * classes.
>   *
> - * <p>Note that methods to accommodate new language constructs could
> - * be added in a source <em>compatible</em> way if they were added as
> - * <em>default methods</em>.  However, default methods are only
> - * available on Java SE 8 and higher releases and the {@code
> - * javax.lang.model.*} packages bundled in Java SE 8 were required to
> - * also be runnable on Java SE 7.  Therefore, default methods
> - * were <em>not</em> used when extending {@code javax.lang.model.*}
> - * to cover Java SE 8 language features.  However, default methods
> - * are used in subsequent revisions of the {@code javax.lang.model.*}
> - * packages that are only required to run on Java SE 8 and higher
> - * platform versions.
> - *
> - * @apiNote
> + * <p>Methods to accommodate new language constructs are expected to
> + * be added as default methods to provide strong source compatibility,
> + * as done for {@link visitModule visitModule}. The implementations of
> + * the default methods will in turn call {@link visitUnknown
> + * visitUnknown}, behavior that will be overridden in concrete
> + * visitors supporting the source version with the new language
> + * construct.
>   *
> - * There are several families of classes implementing this visitor
> + * <p>There are several families of classes implementing this visitor
>   * interface in the {@linkplain javax.lang.model.util util
>   * package}. The families follow a naming pattern along the lines of
>   * {@code FooVisitor}<i>N</i> where <i>N</i> indicates the
> --- 
> old/src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor6.java 
> 2020-02-26 13:13:01.560880601 -0800
> +++ 
> new/src/java.compiler/share/classes/javax/lang/model/util/AbstractElementVisitor6.java 
> 2020-02-26 13:13:01.196880601 -0800
> @@ -36,7 +36,9 @@
>   * appropriate for the {@link SourceVersion#RELEASE_6 RELEASE_6}
>   * source version.
>   *
> - * <p> <b>WARNING:</b> The {@code ElementVisitor} interface
> + * @apiNote
> + *
> + * <strong>WARNING:</strong> The {@code ElementVisitor} interface
>   * implemented by this class may have methods added to it in the
>   * future to accommodate new, currently unknown, language structures
>   * added to future versions of the Java™ programming language.
> @@ -46,12 +48,12 @@
>   * methods with names beginning with {@code "visit"}.
>   *
>   * <p>When such a new visit method is added, the default
> - * implementation in this class will be to call the {@link
> + * implementation in this class will be to directly or indirectly 
> call the {@link
>   * #visitUnknown visitUnknown} method.  A new abstract element visitor
>   * class will also be introduced to correspond to the new language
>   * level; this visitor will have different default behavior for the
> - * visit method in question.  When the new visitor is introduced, all
> - * or portions of this visitor may be deprecated.
> + * visit method in question.  When a new visitor is introduced,
> + * portions of this visitor class may be deprecated, including its 
> constructors.
>   *
>   * @param <R> the return type of this visitor's methods. Use {@link
>   *            Void} for visitors that do not need to return results.
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/compiler-dev/attachments/20200305/a0c513f4/attachment.htm>