Second iteration on updating pthreads' documentation

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@341641 c90b9560-bf6c-de11-be94-00142212c4b1

reference/pthreads/book.xml

@@ -35,10 +35,10 @@
   </para>
   <para>
    The <classname>Worker</classname> class has a persistent state, and will be
-   available from the call to <methodname>Worker::start</methodname> until the
-   object goes out of scope, or is explicitly shutdown (via
-   <methodname>Worker::shutdown</methodname>). Any context with a reference to
-   the worker object can stack tasks onto the Worker (via 
+   available from the call to <methodname>Thread::start</methodname> (an
+   inherited method) until the object goes out of scope, or is explicitly
+   shutdown (via <methodname>Worker::shutdown</methodname>). Any context with a
+   reference to the worker object can stack tasks onto the Worker (via 
    <methodname>Worker::stack</methodname>), where these tasks will be executed
    by the worker in a separate thread. The <literal>run</literal> method of a
    worker object will be executed before any objects on the worker's stack,
@@ -61,18 +61,27 @@
   </caution>
   <para>
    The <classname>Volatile</classname> class is new to pthreads v3. It is used
-   to denote mutable properties of classes.
+   to denote mutable <classname>Threaded</classname> properties of
+   <classname>Threaded</classname> classes (since these are now immutable by
+   default).
   </para>
   <para>
- Synchronization:
- All of the objects that pthreads creates have built in synchronization in the ( familiar to java programmers ) form of ::wait and ::notify. 
- Calling ::wait on an object will cause the context to wait for another context to call ::notify on the same object. 
- This allows for powerful synchronization between Threaded Objects in PHP.
+   Synchronization is an important ability when threading. All of the objects
+   that pthreads creates have built in synchronization in the (which will be
+   familiar to java programmers) form of
+   <methodname>Threaded::wait</methodname> and
+   <methodname>Threaded::notify</methodname>. Calling
+   <methodname>Threaded::wait</methodname> on an object will cause the context
+   to wait for another context to call
+   <methodname>Threaded::notify</methodname> on the same object. This mechanism
+   allows for powerful synchronization between <classname>Threaded</classname>
+   objects in PHP.
   </para>
   <caution>
   <para>
- Any objects that are intended for use in the multi-threaded parts of your application should extend Threaded.
-  </para> 
+   Any objects that are intended for use in the multi-threaded parts of your
+   application should extend <classname>Threaded</classname>.
+  </para>
   </caution>
   <para>
  Method Modifiers:

reference/pthreads/threaded/iswaiting.xml

@@ -7,6 +7,14 @@
   <refpurpose>State Detection</refpurpose>
  </refnamediv>
 
+ <refsynopsisdiv>
+  <warning>
+   <para>
+    This method has been removed in pthreads v3.
+   </para>
+  </warning>
+ </refsynopsisdiv>
+
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>