Updates for the javadocs of declarative (#7749).

Change-Id: I623ba0c17673144f0886556937d25f80ea1f3ffd

9 files changed, 97 insertions, 100 deletions

diff --git a/server/src/com/vaadin/ui/AbstractComponent.java b/server/src/com/vaadin/ui/AbstractComponent.java
index 5f9ce0edcd..5b7492dbdb 100644
--- a/server/src/com/vaadin/ui/AbstractComponent.java
+++ b/server/src/com/vaadin/ui/AbstractComponent.java
@@ -965,7 +965,7 @@ public abstract class AbstractComponent extends AbstractClientConnector
         for (Attribute a : attr) {
             if (!a.getKey().startsWith(":") && !supported.contains(a.getKey())) {
                 getLogger().info(
-                        "Unsupported attribute found when synchronizing from design : "
+                        "Unsupported attribute found when reading from design : "
                                 + a.getKey());
             }
         }
@@ -1041,8 +1041,8 @@ public abstract class AbstractComponent extends AbstractClientConnector
     }
 
     /**
-     * Synchronizes the size of this component from the given design attributes.
-     * If the attributes do not contain relevant size information, defaults is
+     * Reads the size of this component from the given design attributes. If the
+     * attributes do not contain relevant size information, defaults is
      * consulted.
      * 
      * @param attributes
@@ -1169,12 +1169,12 @@ public abstract class AbstractComponent extends AbstractClientConnector
 
     /**
      * Returns a collection of attributes that do not require custom handling
-     * when synchronizing from design. These are typically attributes of some
+     * when reading or writing design. These are typically attributes of some
      * primitive type. The default implementation searches setters with
      * primitive values
      * 
-     * @return a collection of attributes that can be synchronized from design
-     *         using the default approach.
+     * @return a collection of attributes that can be read and written using the
+     *         default approach.
      */
     private Collection<String> getDefaultAttributes() {
         Collection<String> attributes = DesignAttributeHandler
@@ -1185,9 +1185,9 @@ public abstract class AbstractComponent extends AbstractClientConnector
 
     /**
      * Returns a collection of attributes that should not be handled by the
-     * basic implementation of the {@link synhronizeFromDesign} and
-     * {@link writeDesign} methods. Typically these are handled in a custom way
-     * in the overridden versions of the above methods
+     * basic implementation of the {@link readDesign} and {@link writeDesign}
+     * methods. Typically these are handled in a custom way in the overridden
+     * versions of the above methods
      * 
      * @return the collection of attributes that are not handled by the basic
      *         implementation
diff --git a/server/src/com/vaadin/ui/AbstractOrderedLayout.java b/server/src/com/vaadin/ui/AbstractOrderedLayout.java
index ae8f3198bf..77c7e3c826 100644
--- a/server/src/com/vaadin/ui/AbstractOrderedLayout.java
+++ b/server/src/com/vaadin/ui/AbstractOrderedLayout.java
@@ -530,7 +530,7 @@ public abstract class AbstractOrderedLayout extends AbstractLayout implements
      */
     @Override
     public void writeDesign(Element design, DesignContext designContext) {
-        // synchronize default attributes
+        // write default attributes
         super.writeDesign(design, designContext);
         // handle margin
         AbstractOrderedLayout def = (AbstractOrderedLayout) designContext
diff --git a/server/src/com/vaadin/ui/AbstractSingleComponentContainer.java b/server/src/com/vaadin/ui/AbstractSingleComponentContainer.java
index 034c285670..24c36fd0cf 100644
--- a/server/src/com/vaadin/ui/AbstractSingleComponentContainer.java
+++ b/server/src/com/vaadin/ui/AbstractSingleComponentContainer.java
@@ -310,7 +310,7 @@ public abstract class AbstractSingleComponentContainer extends
      */
     @Override
     public void writeDesign(Element design, DesignContext designContext) {
-        // synchronize default attributes (also clears children and attributes)
+        // write default attributes (also clears children and attributes)
         super.writeDesign(design, designContext);
         AbstractSingleComponentContainer def = designContext
                 .getDefaultInstance(this);
diff --git a/server/src/com/vaadin/ui/CssLayout.java b/server/src/com/vaadin/ui/CssLayout.java
index f3ae6c0695..528b34a28f 100644
--- a/server/src/com/vaadin/ui/CssLayout.java
+++ b/server/src/com/vaadin/ui/CssLayout.java
@@ -382,7 +382,7 @@ public class CssLayout extends AbstractLayout implements LayoutClickNotifier {
      */
     @Override
     public void writeDesign(Element design, DesignContext designContext) {
-        // synchronize default attributes
+        // write default attributes
         super.writeDesign(design, designContext);
         CssLayout def = designContext.getDefaultInstance(this);
         // handle children
diff --git a/server/src/com/vaadin/ui/declarative/Design.java b/server/src/com/vaadin/ui/declarative/Design.java
index 138214af6b..ff564fabc3 100644
--- a/server/src/com/vaadin/ui/declarative/Design.java
+++ b/server/src/com/vaadin/ui/declarative/Design.java
@@ -16,7 +16,6 @@
 package com.vaadin.ui.declarative;
 
 import java.beans.IntrospectionException;
-import java.io.BufferedWriter;
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
@@ -39,10 +38,11 @@ import com.vaadin.ui.declarative.DesignContext.ComponentCreatedEvent;
 import com.vaadin.ui.declarative.DesignContext.ComponentCreationListener;
 
 /**
- * Design is used for parsing a component hierarchy from an html file and,
- * conversely, for generating an html tree representation corresponding to a
- * given component hierarchy. For both parsing and tree generation the component
- * hierarchy must contain a single root.
+ * Design is used for reading a component hierarchy from an html string or input
+ * stream and, conversely, for writing an html representation corresponding to a
+ * given component hierarchy. The component hierarchy must contain one root
+ * component. An empty component hierarchy can be represented using null as the
+ * root node.
  * 
  * 
  * @since 7.4
@@ -51,7 +51,7 @@ import com.vaadin.ui.declarative.DesignContext.ComponentCreationListener;
 public class Design implements Serializable {
     /**
      * Parses the given input stream into a jsoup document
-     *
+     * 
      * @param html
      *            the stream containing the design
      * @return the parsed jsoup document
@@ -69,14 +69,14 @@ public class Design implements Serializable {
 
     /**
      * Constructs a component hierarchy from the design specified as an html
-     * document. The component hierarchy must contain exactly one top-level
-     * Component. The component should be located under <body>, but also invalid
-     * html containing the hierarchy without <html>, <head> and <body> tags is
-     * accepted. You can optionally pass instance for the root component with
-     * some uninitialized instance fields. The fields will be automatically
-     * populated when parsing the design based on the component ids, local ids,
-     * and captions of the components in the design.
-     *
+     * document. The hierarchy must contain at most one top-level component,
+     * which should be located under <body>. Also invalid html containing the
+     * hierarchy without <html>, <head> and <body> tags is accepted. You can
+     * optionally pass instance for the root component with some uninitialized
+     * instance fields. The fields will be automatically populated when parsing
+     * the design based on the component ids, local ids, and captions of the
+     * components in the design.
+     * 
      * @param html
      *            the html document describing the component design
      * @param rootInstance
@@ -95,14 +95,14 @@ public class Design implements Serializable {
 
     /**
      * Constructs a component hierarchy from the design specified as an html
-     * document given as a string. The component hierarchy must contain exactly
-     * one top-level Component. The component should be located under <body>,
-     * but also invalid html containing the hierarchy without <html>, <head> and
-     * <body> tags is accepted. You can optionally pass instance for the root
-     * component with some uninitialized instance fields. The fields will be
-     * automatically populated when parsing the design based on the component
-     * ids, local ids, and captions of the components in the design.
-     *
+     * document given as a string. The hierarchy must contain at most one
+     * top-level component, which should be located under <body>. Also invalid
+     * html containing the hierarchy without <html>, <head> and <body> tags is
+     * accepted. You can optionally pass instance for the root component with
+     * some uninitialized instance fields. The fields will be automatically
+     * populated when parsing the design based on the component ids, local ids,
+     * and captions of the components in the design.
+     * 
      * @param html
      *            the html document describing the component design
      * @param rootInstance
@@ -124,9 +124,9 @@ public class Design implements Serializable {
      * tree.
      * 
      * If a component root is given, the component instances created during
-     * synchronizing the design are assigned to its member fields based on their
-     * id, local id, and caption
-     *
+     * reading the design are assigned to its member fields based on their id,
+     * local id, and caption
+     * 
      * @param doc
      *            the html tree
      * @param componentRoot
@@ -151,9 +151,9 @@ public class Design implements Serializable {
      * tree.
      * 
      * If a component root is given, the component instances created during
-     * synchronizing the design are assigned to its member fields based on their
-     * id, local id, and caption
-     *
+     * reading the design are assigned to its member fields based on their id,
+     * local id, and caption
+     * 
      * @param doc
      *            the html tree
      * @param componentRoot
@@ -218,13 +218,14 @@ public class Design implements Serializable {
     }
 
     /**
-     * Generates an html tree representation representing the component
-     * hierarchy having the given root. The hierarchy is stored under <body> in
-     * the tree. The generated tree corresponds to a valid html document.
-     *
-     *
-     * @param root
-     *            the root of the component hierarchy
+     * Generates an html tree representation of the component hierarchy having
+     * the root designContext.getRootComponent(). The hierarchy is stored under
+     * <body> in the tree. The generated tree represents a valid html document.
+     * 
+     * 
+     * @param designContext
+     *            a DesignContext object specifying the root component
+     *            (designContext.getRootComponent()) of the hierarchy
      * @return an html tree representation of the component hierarchy
      */
     private static Document createHtml(DesignContext designContext) {
@@ -249,20 +250,6 @@ public class Design implements Serializable {
     }
 
     /**
-     * Generates an html file corresponding to the component hierarchy with the
-     * given root.
-     *
-     * @param writer
-     * @param root
-     * @throws IOException
-     */
-    private static void createHtml(BufferedWriter writer, DesignContext ctx)
-            throws IOException {
-        String docAsString = createHtml(ctx).toString();
-        writer.write(docAsString);
-    }
-
-    /**
      * Loads a design for the given root component.
      * <p>
      * This methods assumes that the component class (or a super class) has been
@@ -358,7 +345,7 @@ public class Design implements Serializable {
      * design. Matching is done based on field name in the component class and
      * id/local id/caption in the design file.
      * <p>
-     * The type of the root component must match the root element in the design
+     * The type of the root component must match the root element in the design.
      * 
      * @param filename
      *            The file name to load. Loaded from the same package as the
@@ -382,14 +369,16 @@ public class Design implements Serializable {
     }
 
     /**
-     * Loads a design from the given stream using the given root component.
+     * Loads a design from the given stream using the given root component. If
+     * rootComponent is null, the type of the root node is read from the design.
      * <p>
      * Any {@link Component} type fields in the root component which are not
      * assigned (i.e. are null) are mapped to corresponding components in the
      * design. Matching is done based on field name in the component class and
      * id/local id/caption in the design file.
      * <p>
-     * The type of the root component must match the root element in the design
+     * If rootComponent is not null, its type must match the type of the root
+     * element in the design
      * 
      * @param stream
      *            The stream to read the design from
@@ -413,13 +402,12 @@ public class Design implements Serializable {
      * Loads a design from the given input stream
      * 
      * @param design
-     *            The input stream which contains the design
+     *            The stream to read the design from
      * @return The root component of the design
      */
     public static Component read(InputStream design) {
         DesignContext context = read(design, null);
         return context.getRootComponent();
-
     }
 
     /**
@@ -427,7 +415,7 @@ public class Design implements Serializable {
      * stream
      * 
      * @param component
-     *            the root component of the component tree to write
+     *            the root component of the component tree
      * @param outputStream
      *            the output stream to write the design to. The design is always
      *            written as UTF-8
@@ -445,8 +433,9 @@ public class Design implements Serializable {
      * the given output stream. The design context is used for writing local ids
      * and other information not available in the component tree.
      * 
-     * @param component
-     *            the root component of the component tree to write
+     * @param designContext
+     *            the DesignContext object specifying the component hierarchy
+     *            and the local id values of the objects
      * @param outputStream
      *            the output stream to write the design to. The design is always
      *            written as UTF-8
@@ -477,4 +466,4 @@ public class Design implements Serializable {
         outputStream.write(doc.html().getBytes());
     }
 
-}
+}
\ No newline at end of file
diff --git a/server/src/com/vaadin/ui/declarative/DesignAttributeHandler.java b/server/src/com/vaadin/ui/declarative/DesignAttributeHandler.java
index 7b0c039e4a..7c106cec44 100644
--- a/server/src/com/vaadin/ui/declarative/DesignAttributeHandler.java
+++ b/server/src/com/vaadin/ui/declarative/DesignAttributeHandler.java
@@ -232,16 +232,12 @@ public class DesignAttributeHandler implements Serializable {
     }
 
     /**
-     * Reads the given attribute from attributes. If the attribute is not found,
-     * the provided default value is returned
+     * Reads the given attribute from attributes.
      * 
      * @param attribute
      *            the attribute key
      * @param attributes
      *            the set of attributes to read from
-     * @param defaultValue
-     *            the default value that is returned if the attribute is not
-     *            found
      * @param outputType
      *            the output type for the attribute
      * @return the attribute value or the default value if the attribute is not
@@ -269,7 +265,7 @@ public class DesignAttributeHandler implements Serializable {
 
     /**
      * Writes the given attribute value to attributes if it differs from the
-     * default attribute value
+     * default attribute value.
      * 
      * @param attribute
      *            the attribute key
@@ -279,8 +275,8 @@ public class DesignAttributeHandler implements Serializable {
      *            the attribute value
      * @param defaultValue
      *            the default attribute value
-     * @param the
-     *            type of the input value
+     * @param inputType
+     *            the type of the input value
      */
     public static <T> void writeAttribute(String attribute,
             Attributes attributes, T value, T defaultValue, Class<T> inputType) {
@@ -377,9 +373,8 @@ public class DesignAttributeHandler implements Serializable {
     }
 
     /**
-     * Creates the decimal format used when writing attributes to the design
+     * Creates the decimal format used when writing attributes to the design.
      * 
-     * @since 7.4
      * @return the decimal format
      */
     private static DecimalFormat getDecimalFormat() {
@@ -622,7 +617,6 @@ public class DesignAttributeHandler implements Serializable {
      * Provides mappings between shortcut keycodes and their representation in
      * design attributes
      * 
-     * @since 7.4
      * @author Vaadin Ltd
      */
     private static class ShortcutKeyMapper implements Serializable {
@@ -721,8 +715,8 @@ public class DesignAttributeHandler implements Serializable {
     /**
      * Converts the given string attribute value to its corresponding boolean.
      * 
-     * An empty string is considered true (true when attribute exists),
-     * otherwise "false" and "true" are supported, all other input will throw an
+     * An empty string and "true" are considered to represent a true value and
+     * "false" to represent a false value. All other input will throw an
      * exception
      * 
      * @param booleanValue
@@ -733,4 +727,4 @@ public class DesignAttributeHandler implements Serializable {
         return "".equals(booleanValue) ? true : Boolean.valueOf(booleanValue);
     }
 
-}
+}
\ No newline at end of file
diff --git a/server/src/com/vaadin/ui/declarative/DesignContext.java b/server/src/com/vaadin/ui/declarative/DesignContext.java
index c5094d7927..25765611aa 100644
--- a/server/src/com/vaadin/ui/declarative/DesignContext.java
+++ b/server/src/com/vaadin/ui/declarative/DesignContext.java
@@ -55,12 +55,12 @@ public class DesignContext implements Serializable {
     public static final String ID_ATTRIBUTE = "id";
     public static final String CAPTION_ATTRIBUTE = "caption";
     public static final String LOCAL_ID_ATTRIBUTE = "_id";
-    // Mappings from ids to components. Modified when synchronizing from design.
+    // Mappings from ids to components. Modified when reading from design.
     private Map<String, Component> idToComponent = new HashMap<String, Component>();
     private Map<String, Component> localIdToComponent = new HashMap<String, Component>();
     private Map<String, Component> captionToComponent = new HashMap<String, Component>();
-    // Mapping from components to local ids. Accessed when synchronizing to
-    // design. Modified when synchronizing from design.
+    // Mapping from components to local ids. Accessed when writing to
+    // design. Modified when reading from design.
     private Map<Component, String> componentToLocalId = new HashMap<Component, String>();
     private Document doc; // required for calling createElement(String)
     // namespace mappings
@@ -329,7 +329,12 @@ public class DesignContext implements Serializable {
     }
 
     /**
+     * Stores the package mappings (prefix -> package name) of this object to
+     * the specified document. The prefixes are stored as <meta> tags under
+     * <head> in the document.
      * 
+     * @param doc
+     *            the Jsoup document tree where the package mappings are stored
      */
     public void storePrefixes(Document doc) {
         Element head = doc.head();
@@ -355,7 +360,7 @@ public class DesignContext implements Serializable {
      * returned Node.
      * 
      * @param childComponent
-     *            The component with state that is synchronized in to the node
+     *            The component with state that is written in to the node
      * @return An html tree node corresponding to the given component. The tag
      *         name of the created node is derived from the class name of
      *         childComponent.
@@ -570,7 +575,7 @@ public class DesignContext implements Serializable {
     /**
      * Returns the root component of a created component hierarchy.
      * 
-     * @return
+     * @return the root component of the hierarchy
      */
     public Component getRootComponent() {
         return rootComponent;
@@ -578,6 +583,9 @@ public class DesignContext implements Serializable {
 
     /**
      * Sets the root component of a created component hierarchy.
+     * 
+     * @param rootComponent
+     *            the root component of the hierarchy
      */
     public void setRootComponent(Component rootComponent) {
         this.rootComponent = rootComponent;
@@ -690,7 +698,7 @@ public class DesignContext implements Serializable {
      *            The component being written
      * @param defaultC
      *            The default instance for the component
-     * @return
+     * @return whether the children of c should be written
      */
     public boolean shouldWriteChildren(Component c, Component defaultC) {
         if (c == getRootComponent()) {
diff --git a/server/src/com/vaadin/ui/declarative/DesignException.java b/server/src/com/vaadin/ui/declarative/DesignException.java
index 071e280b78..01482f84b0 100644
--- a/server/src/com/vaadin/ui/declarative/DesignException.java
+++ b/server/src/com/vaadin/ui/declarative/DesignException.java
@@ -16,6 +16,12 @@
 package com.vaadin.ui.declarative;
 
 @SuppressWarnings("serial")
+/**
+ * An exception that is used when reading or writing a design fails.
+ * 
+ * @since 7.4 
+ * @author Vaadin Ltd
+ */
 public class DesignException extends RuntimeException {
 
     public DesignException() {
@@ -30,4 +36,4 @@ public class DesignException extends RuntimeException {
         super(message, e);
     }
 
-}
+}
\ No newline at end of file
diff --git a/server/src/com/vaadin/ui/declarative/FieldBinder.java b/server/src/com/vaadin/ui/declarative/FieldBinder.java
index 4826c2be64..af82d9c58c 100644
--- a/server/src/com/vaadin/ui/declarative/FieldBinder.java
+++ b/server/src/com/vaadin/ui/declarative/FieldBinder.java
@@ -45,7 +45,7 @@ public class FieldBinder implements Serializable {
     private Map<String, Field> fieldMap = new HashMap<String, Field>();
 
     /**
-     * Creates a new instance of LayoutFieldBinder
+     * Creates a new instance of LayoutFieldBinder.
      * 
      * @param design
      *            the design class instance containing the fields to bind
@@ -57,7 +57,7 @@ public class FieldBinder implements Serializable {
     }
 
     /**
-     * Creates a new instance of LayoutFieldBinder
+     * Creates a new instance of LayoutFieldBinder.
      * 
      * @param design
      *            the instance containing the fields
@@ -76,7 +76,7 @@ public class FieldBinder implements Serializable {
     }
 
     /**
-     * Returns a collection of field names that are not bound
+     * Returns a collection of field names that are not bound.
      * 
      * @return a collection of fields assignable to Component that are not bound
      */
@@ -104,7 +104,7 @@ public class FieldBinder implements Serializable {
     }
 
     /**
-     * Resolves the fields of the design class instance
+     * Resolves the fields of the design class instance.
      */
     private void resolveFields(Class<?> classWithFields) {
         for (Field memberField : getFieldsInDeclareOrder(classWithFields)) {
@@ -217,7 +217,7 @@ public class FieldBinder implements Serializable {
 
     /**
      * Converts the given identifier to a valid field name by stripping away
-     * illegal character and setting the first letter of the name to lowercase
+     * illegal character and setting the first letter of the name to lower case.
      * 
      * @param identifier
      *            the identifier to be converted to field name
@@ -242,10 +242,10 @@ public class FieldBinder implements Serializable {
     }
 
     /**
-     * Returns an array containing Field objects reflecting all the fields of
-     * the class or interface represented by this Class object. The elements in
-     * the array returned are sorted in declare order. The fields in
-     * superclasses are excluded.
+     * Returns a list containing Field objects reflecting all the fields of the
+     * class or interface represented by this Class object. The elements in the
+     * returned list are sorted in declare order. The fields in superclasses are
+     * excluded.
      * 
      * @param searchClass
      *            the class to be scanned for fields