Re: JDK 9 RFR of JDK-8053918: make the spec for @Documented comprehensible
How about as a first sentence "The Documented meta-annotation indicates whether or not annotations of the annotation types it annotates are considered part of the public contract of the elements they in turn annotate." (Admittedly still a bit convoluted.) -Joe On 5/11/2015 4:07 PM, Jonathan Gibbons wrote:
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
Still a bit convoluted, but the mean time to comprehension is significant less than that of the original. -- Jon On 05/11/2015 04:16 PM, Joseph D. Darcy wrote:
How about as a first sentence
"The Documented meta-annotation indicates whether or not annotations of the annotation types it annotates are considered part of the public contract of the elements they in turn annotate."
(Admittedly still a bit convoluted.)
-Joe
On 5/11/2015 4:07 PM, Jonathan Gibbons wrote:
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
Option A: If the annotation @Documented is present on the declaration of an annotation type T, then any @T annotation on an element is considered part of the element's public contract. Option B: The annotation type Documented is used to indicate that annotations of a given annotation type (namely, the type meta-annotated with @Documented) are considered part of the public contract of the elements they annotate. On 5/11/2015 4:16 PM, Joseph D. Darcy wrote:
How about as a first sentence
"The Documented meta-annotation indicates whether or not annotations of the annotation types it annotates are considered part of the public contract of the elements they in turn annotate."
(Admittedly still a bit convoluted.)
-Joe
On 5/11/2015 4:07 PM, Jonathan Gibbons wrote:
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
participants (3)
-
Alex Buckley
-
Jonathan Gibbons
-
Joseph D. Darcy