programming guide watches section should clarify server/clientlib role in data/child watch maint.

git-svn-id: https://svn.apache.org/repos/asf/hadoop/zookeeper/trunk@740141 13f79535-47bb-0310-9956-ffa450edef68

CHANGES.txt

@@ -148,6 +148,9 @@ flavio via mahadev)
    
    ZOOKEEPER-286. Make GenerateLoad use InstanceContainers. (breed via mahadev)
 
+   ZOOKEEPER-220. programming guide watches section should clarify
+   server/clientlib role in data/child watch maint. (breed via phunt)
+
 NEW FEATURES:
 
    ZOOKEEPER-276. Bookkeeper contribution (Flavio and Luca Telloli via mahadev)

docs/zookeeperProgrammers.html

@@ -859,15 +859,21 @@ document.write("Last Published: " + document.lastModified);
 </p>
 
         
-<p>This refers to the different ways a node can change. ZooKeeper
-        maintains two lists of watches: data watches and child watches.
-        getData() and exists() set data watches. getChildren() sets child
-        watches. Thus, setData() will trigger data watches for the znode being
-        set (assuming the set is successful). A successful create() will
-        trigger a data watch for the znode being created and a child watch for
-        the parent znode. A successful delete() will trigger both a data watch
-        and a child watch (since there can be no more children) for a znode
-        being deleted as well as a child watch for the parent znode.</p>
+<p>This refers to the different ways a node can change.  It
+        helps to think of ZooKeeper as maintaining two lists of
+        watches: data watches and child watches.  getData() and
+        exists() set data watches. getChildren() sets child
+        watches. Alternatively, it may help to think of watches being
+        set according to the kind of data returned. getData() and
+        exists() return information about the data of the node,
+        whereas getChildren() returns a list of children.  Thus,
+        setData() will trigger data watches for the znode being set
+        (assuming the set is successful). A successful create() will
+        trigger a data watch for the znode being created and a child
+        watch for the parent znode. A successful delete() will trigger
+        both a data watch and a child watch (since there can be no
+        more children) for a znode being deleted as well as a child
+        watch for the parent znode.</p>
       
 </li>
     

src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml

@@ -467,15 +467,21 @@
         <para><emphasis role="bold">The data for which the watch was
         set</emphasis></para>
 
-        <para>This refers to the different ways a node can change. ZooKeeper
-        maintains two lists of watches: data watches and child watches.
-        getData() and exists() set data watches. getChildren() sets child
-        watches. Thus, setData() will trigger data watches for the znode being
-        set (assuming the set is successful). A successful create() will
-        trigger a data watch for the znode being created and a child watch for
-        the parent znode. A successful delete() will trigger both a data watch
-        and a child watch (since there can be no more children) for a znode
-        being deleted as well as a child watch for the parent znode.</para>
+        <para>This refers to the different ways a node can change.  It
+        helps to think of ZooKeeper as maintaining two lists of
+        watches: data watches and child watches.  getData() and
+        exists() set data watches. getChildren() sets child
+        watches. Alternatively, it may help to think of watches being
+        set according to the kind of data returned. getData() and
+        exists() return information about the data of the node,
+        whereas getChildren() returns a list of children.  Thus,
+        setData() will trigger data watches for the znode being set
+        (assuming the set is successful). A successful create() will
+        trigger a data watch for the znode being created and a child
+        watch for the parent znode. A successful delete() will trigger
+        both a data watch and a child watch (since there can be no
+        more children) for a znode being deleted as well as a child
+        watch for the parent znode.</para>
       </listitem>
     </itemizedlist>