From 9c0eeb4b697ffa1db8f44a91724c9d612e4add50 Mon Sep 17 00:00:00 2001
From: Henri Sara <hesara@vaadin.com>
Date: Mon, 23 Nov 2015 12:23:12 +0200
Subject: [PATCH] Add javadoc in ServerConnector

Add missing javadoc for ServerConnector.get/setChildren().

Change-Id: I7ba143d41602a5f2a069635911a0ea61a92806e6
---
 .../vaadin/client/HasComponentsConnector.java | 18 +++++++++----
 .../com/vaadin/client/ServerConnector.java    | 25 +++++++++++++++++++
 2 files changed, 38 insertions(+), 5 deletions(-)

diff --git a/client/src/com/vaadin/client/HasComponentsConnector.java b/client/src/com/vaadin/client/HasComponentsConnector.java
index 3d8df3b8cd..19b93edd61 100644
--- a/client/src/com/vaadin/client/HasComponentsConnector.java
+++ b/client/src/com/vaadin/client/HasComponentsConnector.java
@@ -45,14 +45,17 @@ public interface HasComponentsConnector extends ServerConnector {
     void updateCaption(ComponentConnector connector);
 
     /**
-     * Returns the children for this connector.
+     * Returns the child components for this connector.
      * <p>
      * The children for this connector are defined as all {@link HasComponents}s
      * whose parent is this {@link HasComponentsConnector}.
-     * </p>
+     * <p>
+     * Note that the method {@link ServerConnector#getChildren()} can return a
+     * larger list of children including both the child components and any
+     * extensions registered for the connector.
      * 
-     * @return A collection of children for this connector. An empty collection
-     *         if there are no children. Never returns null.
+     * @return A collection of child components for this connector. An empty
+     *         collection if there are no children. Never returns null.
      */
     public List<ComponentConnector> getChildComponents();
 
@@ -65,9 +68,14 @@ public interface HasComponentsConnector extends ServerConnector {
      * {@link ConnectorHierarchyChangeHandler#onConnectorHierarchyChange(ConnectorHierarchyChangeEvent)}
      * . The event method is called only when the hierarchy has been updated for
      * all connectors.
+     * <p>
+     * Note that this method is separate from
+     * {@link ServerConnector#setChildren(List)} and contains only child
+     * components. Both methods are called separately by the framework if the
+     * connector implements {@link HasComponentsConnector}.
      * 
      * @param children
-     *            The new child connectors
+     *            The new child connectors (components only)
      */
     public void setChildComponents(List<ComponentConnector> children);
 
diff --git a/client/src/com/vaadin/client/ServerConnector.java b/client/src/com/vaadin/client/ServerConnector.java
index 4eaa7bc086..0bc2ac9995 100644
--- a/client/src/com/vaadin/client/ServerConnector.java
+++ b/client/src/com/vaadin/client/ServerConnector.java
@@ -162,8 +162,33 @@ public interface ServerConnector extends Connector {
 
     public void updateEnabledState(boolean enabledState);
 
+    /**
+     * Sets the children for this connector. This method should only be called
+     * by the framework to ensure that the connector hierarchy on the client
+     * side and the server side are in sync.
+     * <p>
+     * Note that this method is separate from
+     * {@link HasComponentsConnector#setChildComponents(List)} and takes both
+     * extensions and child components. Both methods are called separately by
+     * the framework if the connector can have child components.
+     * 
+     * @param children
+     *            The new child connectors (extensions and/or components)
+     */
     public void setChildren(List<ServerConnector> children);
 
+    /**
+     * Returns the child connectors for this connector (child components and
+     * extensions).
+     * <p>
+     * Note that the method {@link HasComponentsConnector#getChildComponents()}
+     * can be used to obtain the subset of child connectors that correspond to
+     * components and not extensions.
+     * 
+     * @return A collection of child connectors (components or extensions) for
+     *         this connector. An empty collection if there are no children.
+     *         Never returns null.
+     */
     public List<ServerConnector> getChildren();
 
     /**
-- 
2.39.5