Add javadoc for @DelegateToWidget (#10980)

Change-Id: I15e731058b615ef478cbe27b465ffdb72f0609b1

1 files changed, 59 insertions, 0 deletions

diff --git a/shared/src/com/vaadin/shared/annotations/DelegateToWidget.java b/shared/src/com/vaadin/shared/annotations/DelegateToWidget.java
index ba661e3f32..9109162a31 100644
--- a/shared/src/com/vaadin/shared/annotations/DelegateToWidget.java
+++ b/shared/src/com/vaadin/shared/annotations/DelegateToWidget.java
@@ -19,11 +19,70 @@ import java.io.Serializable;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Target;
 
+/**
+ * Signals that the property value from a state class should be forwarded to the
+ * Widget of the corresponding connector instance.
+ * <p>
+ * When this annotation is present on a field or on a setter method, the
+ * framework will call the corresponding setter in the Connector's Widget
+ * instance with the current state property value whenever it has been changed.
+ * This is happens after firing
+ * {@link com.vaadin.client.ConnectorHierarchyChangeEvent}s but before firing
+ * any {@link com.vaadin.client.communication.StateChangeEvent}.
+ * <p>
+ * Take for example a state class looking like this:
+ * 
+ * <pre>
+ * public class MyComponentState extends AbstractComponentState {
+ *     &#064;DelegateToWidget
+ *     public String myProperty;
+ * }
+ * </pre>
+ * 
+ * Whenever <code>myProperty</code> is changed, the framework will call code
+ * like this:
+ * 
+ * <pre>
+ * connector.getWidget().setMyProperty(connector.getState().myProperty);
+ * </pre>
+ * 
+ * <p>
+ * By default, the Widget method to call is derived from the property name, but
+ * {@link #value()} in the annotation can be used to provide a custom method
+ * name, e.g. {@code @DelegateToWidget("someSpecialName")}.
+ * 
+ * @since 7.0.0
+ * @author Vaadin Ltd
+ */
 @Target({ ElementType.METHOD, ElementType.FIELD })
 public @interface DelegateToWidget {
+    /**
+     * Defines the name of the Widget method to call when the annotated state
+     * property has changed. If no value is defined, the method name will be
+     * derived from the property name, so e.g. a field named
+     * <code>myProperty</code> will delegate to a method named
+     * <code>setMyProperty</code>.
+     * 
+     * @return the name of the method to delegate to, or empty string to use the
+     *         default name
+     */
     public String value() default "";
 
+    /**
+     * Internal helper for handling default values in a uniform way both at
+     * runtime and during widgetset compilation.
+     */
     public static class Helper implements Serializable {
+        /**
+         * Gets the name of the method to delegate to for a given property name
+         * and annotation value.
+         * 
+         * @param propertyName
+         *            the name of the delegated property
+         * @param annotationValue
+         *            the {@link DelegateToWidget#value()} of the annotation
+         * @return the name of the method to delegate to
+         */
         public static String getDelegateTarget(String propertyName,
                 String annotationValue) {
             String name = annotationValue;