JDK 9 RFR of JDK-8053918: make the spec for @Documented comprehensible
joe darcy
joe.darcy at oracle.com
Mon May 11 22:58:42 UTC 2015
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
More information about the compiler-dev
mailing list