JDK 9 RFR of JDK-8053918: make the spec for @Documented comprehensible

[Jonathan Gibbons]

Although the original "first sentence" is somewhat hard to parse, at 
least there is a single "first sentence"  The rewrite doesn't seem to 
have such a succint first sentence.

If I were to change just one word in the original first sentence, I 
would change "with" to "on":

- * Indicates that annotations with a type are to be documented by javadoc
- * and similar tools by default.
+ * Indicates that annotations on a type are to be documented by javadoc
+* and similar tools by default.

-- Jon

On 05/11/2015 03:58 PM, joe darcy wrote:
> Hello,
>
> Some are of the opinion that the specification for the Documented 
> meta-annotation type could be clarified.
>
>     JDK-8053918: make the spec for @Documented comprehensible
>     http://cr.openjdk.java.net/~darcy/8053918.0/
>
> Please review the patch below which aims to accomplish this.
>
> Thanks,
>
> -Joe
>
> --- 
> old/src/java.base/share/classes/java/lang/annotation/Documented.java 
> 2015-05-11 15:54:37.273033243 -0700
> +++ 
> new/src/java.base/share/classes/java/lang/annotation/Documented.java 
> 2015-05-11 15:54:37.153033240 -0700
> @@ -26,12 +26,20 @@
>  package java.lang.annotation;
>
>  /**
> - * Indicates that annotations with a type are to be documented by 
> javadoc
> - * and similar tools by default.  This type should be used to 
> annotate the
> - * declarations of types whose annotations affect the use of annotated
> - * elements by their clients.  If a type declaration is annotated with
> - * Documented, its annotations become part of the public API
> - * of the annotated elements.
> + * When an annotation type <i>A</i> is annotated with {@code
> + * Documented}, the presence and value of annotations of type <i>A</i>
> + * are a part of the public contract of the elements <i>A</i>
> + * annotates.
> + *
> + * Conversely, if an annotation type <i>B</i> is <em>not</em>
> + * annotated with {@code Documented}, the presence and value of
> + * <i>B</i>annotations are <em>not</em> part of the public contract of
> + * the elements <i>B</i> annotates.
> + *
> + * Concretely, if an annotation type is annotated with {@code
> + * Documented}, by default a tool like javadoc will display
> + * annotations of that type in its output while annotations of
> + * annotation types without {@code Documented} will not be displayed.
>   *
>   * @author  Joshua Bloch
>   * @since 1.5
>