[jackson-annotations] 81/207: Improve javadocs to indicate that `@JsonProperty` value of "" is invalid for Creators.

[Timo Aaltonen]

This is an automated email from the git hooks/post-receive script.

tjaalton pushed a commit to branch master
in repository jackson-annotations.

commit 99844fa73152edca3784f64a8148c6636e9f4db7
Author: Tatu Saloranta <tsaloranta at salesforce.com>
Date:   Fri Aug 31 10:42:58 2012 -0700

    Improve javadocs to indicate that `@JsonProperty` value of "" is invalid for Creators.
---
 .../com/fasterxml/jackson/annotation/JsonCreator.java   | 17 +++++++++++++++++
 .../com/fasterxml/jackson/annotation/JsonProperty.java  | 12 ++++++++----
 2 files changed, 25 insertions(+), 4 deletions(-)

diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonCreator.java b/src/main/java/com/fasterxml/jackson/annotation/JsonCreator.java
index 910f5cb..0888d70 100644
--- a/src/main/java/com/fasterxml/jackson/annotation/JsonCreator.java
+++ b/src/main/java/com/fasterxml/jackson/annotation/JsonCreator.java
@@ -9,6 +9,23 @@ import java.lang.annotation.Target;
  * Marker annotation that can be used to define constructors and factory
  * methods as one to use for instantiating new instances of the associated
  * class.
+ *<p>
+ * NOTE: when annotating creator methods (constructors, factory methods),
+ * method must either be:
+ *<ul>
+ * <li>Single-argument constructor/factory method without {@link JsonProperty}
+ *    annotation for the argument: if so, this is so-called "delegate creator",
+ *    in which case Jackson first binds JSON into type of the argument, and
+ *    then calls creator
+ *   </li>
+ * <li>Constructor/factory method where <b>every argument</b> is annotated with
+ *   either {@link JsonProperty} or {@link JacksonInject}, to indicate name
+ *   of property to bind to
+ *  </li>
+ * </ul>
+ * Also note that all {@link JsonProperty} annotations MUST use actual name
+ * (NOT empty String for "default"): this because Java bytecode does not
+ * retain names of method or constructor arguments.
  */
 @Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR})
 @Retention(RetentionPolicy.RUNTIME)
diff --git a/src/main/java/com/fasterxml/jackson/annotation/JsonProperty.java b/src/main/java/com/fasterxml/jackson/annotation/JsonProperty.java
index d256677..ca04f89 100644
--- a/src/main/java/com/fasterxml/jackson/annotation/JsonProperty.java
+++ b/src/main/java/com/fasterxml/jackson/annotation/JsonProperty.java
@@ -24,9 +24,13 @@ import java.lang.annotation.Target;
 public @interface JsonProperty
 {
     /**
-     * Defines name of the logical property, i.e. Json object field
-     * name to use for the property: if empty String (which is the
-     * default), will use name of the field that is annotated.
+     * Defines name of the logical property, i.e. JSON object field
+     * name to use for the property. If value is empty String (which is the
+     * default), will try to use name of the field that is annotated.
+     * Note that there is
+     * <b>no default name available for constructor arguments</b>,
+     * meaning that
+     * <b>Empty String is not a valid value for constructor arguments</b>
      */
     String value() default "";
 
@@ -41,7 +45,7 @@ public @interface JsonProperty
      *<p>
      * Note that as of 2.0, this property is NOT used by
      * <code>BeanDeserializer</code>: support is expected to be
-     * added for later minor versions.
+     * added for a later minor version.
      * 
      * @since 2.0
      */

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-java/jackson-annotations.git