From 2736c3b45f2b48d5dbf20f56dffcffa06c23b6bc Mon Sep 17 00:00:00 2001
From: Thomas Punt <tpunt@php.net>
Date: Tue, 10 Jan 2017 22:56:01 +0000
Subject: [PATCH] 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               | 31 +++++++++++++++--------
 reference/pthreads/threaded/iswaiting.xml |  8 ++++++
 2 files changed, 28 insertions(+), 11 deletions(-)

diff --git a/reference/pthreads/book.xml b/reference/pthreads/book.xml
index da9481c296..292dbe94a2 100644
--- a/reference/pthreads/book.xml
+++ b/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:
diff --git a/reference/pthreads/threaded/iswaiting.xml b/reference/pthreads/threaded/iswaiting.xml
index ab6df55a1e..f3a89461f3 100644
--- a/reference/pthreads/threaded/iswaiting.xml
+++ b/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>