Javadoc improvements wrt #384 (regarding jackson xml annotations)

src/main/java/com/fasterxml/jackson/dataformat/xml/annotation/JacksonXmlCData.java

@@ -7,15 +7,16 @@
 
 /**
  * Adding this annotation will result in value of the property to be serialized
- * within a CData tag.  Only use on String properties and String collections.
+ * within an xml {@code CDATA} section.  Only use on String properties and String collections.
  */
 @Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER })
 @Retention(RetentionPolicy.RUNTIME)
 public @interface JacksonXmlCData
 {
     /**
-     * Whether the property text should always be within a CData block
-     * when serialized.
+     * Whether the property text should always be within a CDATA section
+     * when serialized. Has no meaning for deserialization; content may come from
+     * any legal character data section (CDATA or regular text segment).
      */
     public boolean value() default true;
 }

src/main/java/com/fasterxml/jackson/dataformat/xml/annotation/JacksonXmlProperty.java

@@ -9,7 +9,21 @@
  * Annotation that can be used to provide XML-specific configuration
  * for properties, above and beyond what
  * {@link com.fasterxml.jackson.annotation.JsonProperty} contains.
- * It is an alternative to using JAXB annotations.
+ * It is mainly an alternative to using JAXB annotations.
+ *<p>
+ * Note that annotation may be used on
+ *<ul>
+ * <li>Fields
+ *  </li>
+ * <li>Setter and getter methods
+ *  </li>
+ * <li>Arguments (parameters) of "Creators" -- annotated constructors and/or
+ *    static factory methods
+ *  </li>
+ * </ul>
+ * but it can NOT be used on argument/parameter of setter methods (or rather
+ * while compiler allows that, will have no effect) -- setter method itself
+ * needs to be annotated.
  */
 @Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})
 @Retention(RetentionPolicy.RUNTIME)

src/main/java/com/fasterxml/jackson/dataformat/xml/annotation/JacksonXmlRootElement.java

@@ -9,6 +9,10 @@
  * Annotation that can be used to define name of root element used
  * for the root-level object when serialized, which normally uses
  * name of the type (class). It is similar to JAXB <code>XmlRootElement</code>.
+ *<p>
+ * Note that annotation has no effect on non-root elements: regular property
+ * values and so on; their name is derived from getter/setter/field, not
+ * from type itself.
  */
 @Target({ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)

src/main/java/com/fasterxml/jackson/dataformat/xml/annotation/JacksonXmlText.java

@@ -8,9 +8,15 @@
  * It will result in value of the property be serialized without element wrapper,
  * as long as there are no element-wrapped other properties (attribute-valued
  * properties are acceptable).
- * It is also similar to core Jackson <code>JsonValue</code> annotation; but
+ * It is also somewhat similar to core Jackson <code>JsonValue</code> annotation; but
  * has to be separate as <code>JsonValue</code> does not allow any other
  * properties.
+ *<p>
+ * Note that only one such property is allowed on a POJO: if multiple properties
+ * are annotated, behavior is not defined.
+ *<p>
+ * Internally properties annotated will be considered to be properties with
+ * no name (that is, with marker {@code ""} (empty String)).
  */
 @Target({ElementType.FIELD, ElementType.METHOD})
 @Retention(RetentionPolicy.RUNTIME)