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

[Alex Buckley]

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
>>>
>>
>