address first round of PR comments

reference/curl/curlsharepersistenthandle.xml

@@ -45,7 +45,7 @@
         <varlistentry xml:id="curlsharepersistenthandle.props.options">
           <term><varname>options</varname></term>
           <listitem>
-            <para>An array of <constant>CURL_LOCK_DATA_*</constant> constants shared in this handle.</para>
+            <para>The <constant>CURL_LOCK_DATA_<replaceable>*</replaceable></constant> constants shared between requests using this handle.</para>
           </listitem>
         </varlistentry>
       </variablelist>

reference/curl/functions/curl-share-init-persistent.xml

@@ -12,7 +12,11 @@
       <methodparam><type>array</type><parameter>share_options</parameter></methodparam>
     </methodsynopsis>
     <para>
-      Initialize a <emphasis role="bold">persistent</emphasis> cURL share handle with the given share options. Unlike <function>curl_share_init</function>, handles created by this function will not be destroyed at the end of the PHP request. If a persistent share handle with the same set of <literal>$share_options</literal> is found, it will be reused.
+      Initialize a <emphasis role="bold">persistent</emphasis> cURL share handle
+      with the given share options. Unlike <function>curl_share_init</function>,
+      handles created by this function will not be destroyed at the end of the
+      PHP request. If a persistent share handle with the same set of
+      <parameter>$share_options</parameter> is found, it will be reused.
     </para>
   </refsect1>
 
@@ -24,10 +28,13 @@
         <term><parameter>share_options</parameter></term>
         <listitem>
           <para>
-            A non-empty array of <constant>CURL_LOCK_DATA_*</constant> constants.
+            A non-empty array of <constant>CURL_LOCK_DATA_<replaceable>*</replaceable></constant> constants.
           </para>
           <para>
-            <emphasis role="bold">Note:</emphasis> <constant>CURL_LOCK_DATA_COOKIE</constant> is not allowed and, if specified, this function will throw a <exceptionname>ValueError</exceptionname>. Sharing cookies between PHP requests may lead to inadvertently mixing up sensitive cookies between users.
+            <emphasis role="bold">Note:</emphasis> <constant>CURL_LOCK_DATA_COOKIE</constant>
+            is not allowed and, if specified, this function will throw a
+            <exceptionname>ValueError</exceptionname>. Sharing cookies between PHP
+            requests may lead to inadvertently mixing up sensitive cookies between users.
           </para>
         </listitem>
       </varlistentry>
@@ -44,20 +51,44 @@
 
   <refsect1 role="errors">
     &reftitle.errors;
-    <simpara>
-      A <exceptionname>ValueError</exceptionname> is thrown when <literal>$share_options</literal> either: is empty, contains <constant>CURL_LOCK_DATA_COOKIE</constant>, or contains a value not matching a <constant>CURL_LOCK_DATA_*</constant> constant.
-    </simpara>
-    <simpara>
-      A <exceptionname>TypeError</exceptionname> is thrown when <literal>$share_options</literal> contains a value that cannot be cast to an integer.
-    </simpara>
+    <itemizedlist>
+      <listitem>
+        <simpara>
+          If <parameter>$share_options</parameter> is empty, this function throws
+          a <exceptionname>ValueError</exceptionname>.
+        </simpara>
+      </listitem>
+      <listitem>
+        <simpara>
+          If <parameter>$share_options</parameter> contains a value not matching
+          a <constant>CURL_LOCK_DATA_<replaceable>*</replaceable></constant>,
+          this function throws a <classname>ValueError</classname>.
+        </simpara>
+      </listitem>
+      <listitem>
+        <simpara>
+          If <parameter>$share_options</parameter> contains
+          <constant>CURL_LOCK_DATA_COOKIE</constant>, this function throws a
+          <exceptionname>ValueError</exceptionname>.
+        </simpara>
+      </listitem>
+      <listitem>
+        <simpara>
+          If <parameter>$share_options</parameter> contains a non-integer value,
+          this function throws a <exceptionname>TypeError</exceptionname>.
+        </simpara>
+      </listitem>
+    </itemizedlist>
   </refsect1>
 
   <refsect1 role="examples">
     &reftitle.examples;
     <example xml:id="function.curl-share-init-persistent.example.basic">
       <title><function>curl_share_init_persistent</function> example</title>
       <para>
-        This example will create a persistent cURL share handle and demonstrate sharing connections between them. If this is executed in a long-lived PHP SAPI, <literal>$sh</literal> will survive between SAPI requests.
+        This example will create a persistent cURL share handle and demonstrate
+        sharing connections between them. If this is executed in a long-lived
+        PHP SAPI, <literal>$sh</literal> will survive between SAPI requests.
       </para>
 
       <programlisting role="php">
@@ -66,14 +97,14 @@
 // Create or retrieve a persistent cURL share handle set to share DNS lookups and connections.
 $sh = curl_share_init([CURL_LOCK_DATA_DNS, CURL_LOCK_DATA_CONNECT]);
 
-// Initialize the first cURL handle and assign the share handle to it
+// Initialize the first cURL handle and assign the share handle to it.
 $ch1 = curl_init("http://example.com/");
 curl_setopt($ch1, CURLOPT_SHARE, $sh);
 
 // Execute the first cURL handle. This may reuse the connection from an earlier SAPI request.
 curl_exec($ch1);
 
-// Initialize the second cURL handle and assign the share handle to it
+// Initialize the second cURL handle and assign the share handle to it.
 $ch2 = curl_init("http://example.com/");
 curl_setopt($ch2, CURLOPT_SHARE, $sh);
 
@@ -94,6 +125,7 @@ curl_close($ch2);
     &reftitle.seealso;
     <simplelist>
       <member><function>curl_setopt</function></member>
+      <member><function>curl_share_init</function></member>
     </simplelist>
   </refsect1>
 

reference/curl/functions/curl-share-init.xml

@@ -103,6 +103,7 @@ curl_close($ch2);
    <simplelist>
     <member><function>curl_share_setopt</function></member>
     <member><function>curl_share_close</function></member>
+    <member><function>curl_share_init_persistent</function></member>
    </simplelist>
   </para>
  </refsect1>