JDK 14 RFR of 8237062: Refine JSR 269 API ahead of Java SE 14 MR

[Jan Lahoda]

Looks good to me.

Jan

On 14. 01. 20 8:00, Joe Darcy wrote:
> Hello,
> 
>  From a pass over the JSR 269 API ahead of its MR for Java SE 14, I 
> noticed some small areas for improvement:
> 
>      http://cr.openjdk.java.net/~darcy/8237062.0/
> 
> The Filer is updated to refer to the Generated annotation that was added 
> to the containing package back in Java SE 9. The largest update is for 
> AnnotatedConstruct to make some reference to how annotations are record 
> components are propagated down to other members.
> 
> Patch below; thanks,
> 
> -Joe
> 
> --- 
> old/src/java.compiler/share/classes/javax/annotation/processing/Filer.java 
> 2020-01-13 22:55:36.206212693 -0800
> +++ 
> new/src/java.compiler/share/classes/javax/annotation/processing/Filer.java 
> 2020-01-13 22:55:36.026302687 -0800
> @@ -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
> @@ -113,7 +113,7 @@
>    * to overwrite existing files that were not generated.
>    *
>    * <p> Processors can indicate a source or class file is generated by
> - * including a {@code javax.annotation.Generated} annotation if the
> + * including a {@link javax.annotation.processing.Generated} annotation 
> if the
>    * environment is configured so that that type is accessible.
>    *
>    * @apiNote Some of the effect of overwriting a file can be
> --- 
> old/src/java.compiler/share/classes/javax/annotation/processing/Processor.java 
> 2020-01-13 22:55:36.578026707 -0800
> +++ 
> new/src/java.compiler/share/classes/javax/annotation/processing/Processor.java 
> 2020-01-13 22:55:36.406112701 -0800
> @@ -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
> @@ -130,7 +130,7 @@
>    * annotations on elements, are ignored when computing whether or not
>    * an annotation type is present.
>    *
> - * <p>An annotation is present if it meets the definition of being
> + * <p>An annotation is <em>present</em> if it meets the definition of 
> being
>    * present given in {@link AnnotatedConstruct}. In brief, an
>    * annotation is considered present for the purposes of discovery if
>    * it is directly present or present via inheritance. An annotation is
> --- 
> old/src/java.compiler/share/classes/javax/lang/model/AnnotatedConstruct.java 
> 2020-01-13 22:55:37.289670733 -0800
> +++ 
> new/src/java.compiler/share/classes/javax/lang/model/AnnotatedConstruct.java 
> 2020-01-13 22:55:37.113758726 -0800
> @@ -1,5 +1,5 @@
>   /*
> - * Copyright (c) 2013, 2019, Oracle and/or its affiliates. All rights 
> reserved.
> + * Copyright (c) 2013, 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
> @@ -60,10 +60,17 @@
>    * the source code of representation of <i>C</i>, then <i>A</i> is
>    * explicitly declared as applying to <i>C</i>.
>    *
> + * An annotation of type <i>AT</i> on a {@linkplain
> + * RecordComponentElement record component} can be implicitly propagated
> + * down to affiliated mandated members. Type annotations modifying the
> + * type of a record component can be also propagated to mandated
> + * members. Propagation of the annotations to mandated members is
> + * governed by rules given in the <cite>The Java™ Language
> + * Specification</cite>.
> + *
>    * If there are multiple annotations of type <i>AT</i> present on
>    * <i>C</i>, then if <i>AT</i> is repeatable annotation type, an
>    * annotation of type <i>ATC</i> is {@linkplain 
> javax.lang.model.util.Elements#getOrigin(AnnotatedConstruct, 
> AnnotationMirror) implicitly declared} on <i>C</i>.
> - *
>    * <li> A representation of <i>A</i> appears in the executable output
>    * for <i>C</i>, such as the {@code RuntimeVisibleAnnotations} or
>    * {@code RuntimeVisibleParameterAnnotations} attributes of a class
>