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

[Joe Darcy]

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