few clarifications for addChildDevice, add getChildDevices and getDev…

…iceNetworkId` (#603)

* few clarifications for addChildDevice, add getChildDevices and getDeviceNetworkId

* add label and completedSetup options

composite-devices/index.rst

@@ -60,7 +60,7 @@ For example, in the Device Handler of the Zooz ZEN20 Z-Wave Power Strip composit
 		state.oldLabel = device.label
 		// Add child devices for all five outlets of Zooz Power Strip
 		for (i in 1..5) {
-		addChildDevice("ZooZ Power Strip Outlet", "${device.deviceNetworkId}-${i}", null,[completedSetup: true, label: "${device.displayName} (CH${i})", isComponent: true, componentName: "ch$i", componentLabel: "Channel $i"])
+    		addChildDevice("ZooZ Power Strip Outlet", "${device.deviceNetworkId}-${i}", null,[completedSetup: true, label: "${device.displayName} (CH${i})", isComponent: true, componentName: "ch$i", componentLabel: "Channel $i"])
 		}
 	}
 
@@ -103,12 +103,12 @@ Next, the below Device Handler code sets up the *outlet* of the Zooz ZEN20 Z-Wav
 		parent.childOff(device.deviceNetworkId)
 	}
 
-In the above example, the method calls, ``parent.childOn(device.deviceNetworkId)`` and ``parent.childOff(device.deviceNetworkId)``, are the means of communication between the parent and the child instances of this composite device. 
+In the above example, the method calls, ``parent.childOn(device.deviceNetworkId)`` and ``parent.childOff(device.deviceNetworkId)``, are the means of communication between the parent and the child instances of this composite device.
 
 Deleting a Composite Device
 ---------------------------
 
-Deleting a composite parent device will delete all children devices. 
+Deleting a composite parent device will delete all children devices.
 For example, deleting the Power Strip itself will delete its outlets as devices from the SmartThings platform.
 
 SmartApps can be configured to control individual outlets as well as the entire power strip.
@@ -118,16 +118,14 @@ If you try to delete a composite device from your SmartThings mobile app, then t
 
 - If the parameter ``isComponent`` is set to ``true``, as shown in the :ref:`composite_device_parent_device_handler` example above, then the device is hidden from the Things view and you will not be presented with the option of deleting child devices individually.
 
-- If the parameter ``isComponent`` is set to ``false``, then you can delete individual child devices. 
+- If the parameter ``isComponent`` is set to ``false``, then you can delete individual child devices.
 
 .. note::
 
 	Note that the following applies for a composite device:
 
-	
+
 
 	- A single SmartApp can control all the components, each independently, sending and receive messages from each component device.
 
 	- A single SmartApp can control all components together in an all-or-nothing fashion.
-
-

ref-docs/device-handler-ref.rst

@@ -130,21 +130,24 @@ The ``parse()`` method may return a map defining the :ref:`event_ref` to create
 
 ----
 
-.. _addChildDevice_DH_ref:    
+.. _addChildDevice_DH_ref:
 
 addChildDevice()
 ----------------
 
-Adds a child device to a Device Handler. An example use is in a composite device Device Handler.
+Adds a child device to a Device Handler.
+An example use is in a composite device Device Handler.
+
+A parent may have multiple children, but only one level of children is allowed (i.e., if a device has a parent, it may not have children itself).
+
 
 **Signature:**
-    ``DeviceWrapper addChildDevice(String namespace, String typeName, String deviceNetworkId, hubId, Map properties)``
+    ``DeviceWrapper addChildDevice(String typeName, String deviceNetworkId, hubId, Map properties)``
 
-**Throws:**
-    ``UnknownDeviceTypeException``
+    ``DeviceWrapper addChildDevice(String namespace, String typeName, String deviceNetworkId, hubId, Map properties)``
 
 **Parameters:**
-    `String`_ ``namespace`` - the namespace for the device. Defaults to ``device.deviceTypeDTO.namespace``.
+    `String`_ ``namespace`` - the namespace for the device. If not specified, defaults to the namespace of the current Device Handler executing the call.
 
     `String`_ ``typeName`` - the device type name
 
@@ -160,10 +163,39 @@ Adds a child device to a Device Handler. An example use is in a composite device
     isComponent    Allowed values are ``true`` and ``false``. When ``true`` hides the device from the Things view and doesn't let it be separately deleted. (Example: This value is ``true`` for the ZooZ ZEN 20 and ``false`` for Hue bridge.)
     componentName  A way to refer to this particular child. It should be a Java Bean name (i.e. no spaces). It is used to refer to the device in the parent's detail view. This option is only needed when ``isComponent`` is ``true``.
     componentLabel The plain-english name (or i18n key) to be used by the UX.
+    completedSetup Specify ``true`` to complete the setup for the child device; ``false`` to have the user complete the installation. It should be ``true`` if ``isComponent`` is true. Defaults to ``false``.
+    label          The label for the device.
     ============== ===========
 
 **Returns:**
-    ``DeviceWrapper`` - The device that was created.
+    :ref:`device_ref` - The device that was created.
+
+**Throws:**
+    ``UnknownDeviceTypeException`` - If a Device Handler with the specified name and namespace is not found.
+
+    ``IllegalArgumentException`` - If the ``deviceNetworkId`` is not specified.
+
+    ``ValidationException`` - If the this device already has a parent.
+
+**Example:**
+
+.. code-block:: groovy
+
+    // on installation, create child devices
+    def installed() {
+        createChildDevices()
+    }
+
+    def createChildDevices() {
+
+        // This device (power strip) has five outlets
+        for (i in 1..5) {
+            // can omit namespace (first arg) if it is the same as this device
+            addChildDevice("smartthings", "Zooz Power Strip Outlet", "${device.deviceNetworkId}-ep${i}", null,
+    				[completedSetup: true, label: "${device.displayName} (CH${i})",
+    				 isComponent: true, componentName: "ch$i", componentLabel: "Channel $i"])
+        }
+    }
 
 ----
 
@@ -600,6 +632,32 @@ Returns the URL of the server where this Device Handler can be reached for API c
 
 ----
 
+.. device_handler_ref_get_child_devices:
+
+getChildDevices()
+-----------------
+
+Gets a list of all child devices for this device.
+
+**Signature:**
+    ``List<ChildDeviceWrapper> getChildDevices()``
+
+**Returns:**
+    `List`_ <:ref:`device_ref`> - a list of child devices for this device
+
+**Example:**
+
+.. code-block:: groovy
+
+    def children = getChildDevices()
+
+    log.debug "device has ${children.size()} children"
+    children.each { child ->
+        log.debug "child ${child.displayName} has deviceNetworkId ${child.deviceNetworkId}"
+    }
+
+----
+
 .. _device_handler_ref_get_color_util:
 
 getColorUtil()

ref-docs/device-ref.rst

@@ -395,6 +395,19 @@ The List of Capabilities provided by this Device.
 
 ----
 
+.. _device_ref_get_device_network_id:
+
+getDeviceNetworkId()
+--------------------
+
+Gets the device network ID for the device.
+
+**Signature:**
+    ``String getDeviceNetworkId()``
+
+**Returns:**
+    `String`_ - the network ID for the device
+
 getDisplayName()
 ----------------