From 483b88c6d244661abca436864dceb561a24f66ec Mon Sep 17 00:00:00 2001
From: Gunnar Morling <gunnar.morling@googlemail.com>
Date: Sun, 25 Jan 2015 11:26:48 +0100
Subject: [PATCH] #271 Improving JavaDocs for @Mapping#expression()

---
 .../src/main/java/org/mapstruct/Mapping.java  | 27 ++++++++++++++-----
 core/src/main/java/org/mapstruct/Mapping.java | 27 ++++++++++++++-----
 2 files changed, 42 insertions(+), 12 deletions(-)

diff --git a/core-jdk8/src/main/java/org/mapstruct/Mapping.java b/core-jdk8/src/main/java/org/mapstruct/Mapping.java
index 9cc7e2b45..0794e4520 100644
--- a/core-jdk8/src/main/java/org/mapstruct/Mapping.java
+++ b/core-jdk8/src/main/java/org/mapstruct/Mapping.java
@@ -92,14 +92,29 @@ public @interface Mapping {
     String constant() default "";
 
     /**
-     * An expression {@link String} based on which the specified target property is to be set. The format is determined
-     * by a type of expression. For instance:
-     * {@code expression = "java(new org.example.TimeAndFormat( s.getTime(), s.getFormat() ))")} will insert the java
-     * expression in the designated {@link #target()} property.
+     * An expression {@link String} based on which the specified target property is to be set.
+     * <p>
+     * Currently, Java is the only supported "expression language" and expressions must be given in form of Java
+     * expressions using the following format: {@code java(<EXPRESSION>)}. For instance the mapping
      * <p>
-     * Either this attribute or {@link #source()} or {@link #constant()} may be specified for a given mapping.
      *
-     * @return A constant {@code String} constant specifying the value for the designated target property
+     * <pre>
+     * {@code @Mapping(
+     *     target = "someProp",
+     *     expression = "java(new TimeAndFormat( s.getTime(), s.getFormat() ))"
+     * )}
+     * </pre>
+     * <p>
+     * will cause the following target property assignment to be generated:
+     * <p>
+     * {@code targetBean.setSomeProp( new TimeAndFormat( s.getTime(), s.getFormat() ) )}.
+     * <p>
+     * Any types referenced in expressions must be given via their fully-qualified name. Alternatively, types can be
+     * imported via {@link Mapper#imports()}.
+     * <p>
+     * Either this attribute, {@link #source()} or {@link #constant()} may be specified for a given mapping.
+     *
+     * @return An expression specifying the value for the designated target property
      */
     String expression() default "";
 
diff --git a/core/src/main/java/org/mapstruct/Mapping.java b/core/src/main/java/org/mapstruct/Mapping.java
index ce367def6..c4226d406 100644
--- a/core/src/main/java/org/mapstruct/Mapping.java
+++ b/core/src/main/java/org/mapstruct/Mapping.java
@@ -90,14 +90,29 @@ public @interface Mapping {
     String constant() default "";
 
     /**
-     * An expression {@link String} based on which the specified target property is to be set. The format is determined
-     * by a type of expression. For instance:
-     * {@code expression = "java(new org.example.TimeAndFormat( s.getTime(), s.getFormat() ))")} will insert the java
-     * expression in the designated {@link #target()} property.
+     * An expression {@link String} based on which the specified target property is to be set.
+     * <p>
+     * Currently, Java is the only supported "expression language" and expressions must be given in form of Java
+     * expressions using the following format: {@code java(<EXPRESSION>)}. For instance the mapping
      * <p>
-     * Either this attribute or {@link #source()} or {@link #constant()} may be specified for a given mapping.
      *
-     * @return A constant {@code String} constant specifying the value for the designated target property
+     * <pre>
+     * {@code @Mapping(
+     *     target = "someProp",
+     *     expression = "java(new TimeAndFormat( s.getTime(), s.getFormat() ))"
+     * )}
+     * </pre>
+     * <p>
+     * will cause the following target property assignment to be generated:
+     * <p>
+     * {@code targetBean.setSomeProp( new TimeAndFormat( s.getTime(), s.getFormat() ) )}.
+     * <p>
+     * Any types referenced in expressions must be given via their fully-qualified name. Alternatively, types can be
+     * imported via {@link Mapper#imports()}.
+     * <p>
+     * Either this attribute, {@link #source()} or {@link #constant()} may be specified for a given mapping.
+     *
+     * @return An expression specifying the value for the designated target property
      */
     String expression() default "";