8053918: make the spec for @Documented comprehensible

Reviewed-by: jjg, abuckley

jdk/src/java.base/share/classes/java/lang/annotation/Documented.java

@@ -26,12 +26,24 @@
 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.
+ * If the annotation {@code @Documented} is present on the declaration
+ * of an annotation type <i>A</i>, then any {@code @A} annotation on
+ * an element is considered part of the element's public contract.
+ *
+ * In more detail, 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