From 1e1ef2743f4c6883585559efc5bc27277a52fad7 Mon Sep 17 00:00:00 2001
From: Andrei Zmievski <andrei@php.net>
Date: Thu, 5 Feb 2009 00:48:47 +0000
Subject: [PATCH] memcached docs progress

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@275198 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/memcached/memcached/fetch.xml       | 54 ++++++++++++--
 reference/memcached/memcached/fetchall.xml    | 55 +++++++++++---
 reference/memcached/memcached/get.xml         |  8 +-
 reference/memcached/memcached/getbykey.xml    |  4 +-
 reference/memcached/memcached/getdelayed.xml  | 74 +++++++++++++++----
 .../memcached/memcached/getdelayedbykey.xml   | 52 +++++--------
 6 files changed, 175 insertions(+), 72 deletions(-)

diff --git a/reference/memcached/memcached/fetch.xml b/reference/memcached/memcached/fetch.xml
index 8cab41411e..46291e0b85 100644
--- a/reference/memcached/memcached/fetch.xml
+++ b/reference/memcached/memcached/fetch.xml
@@ -1,20 +1,21 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 
 <refentry xml:id="memcached.fetch" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::fetch</refname>
-  <refpurpose>The fetch purpose</refpurpose>
+  <refpurpose>Fetch the next result</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <modifier>public</modifier> <type>void</type><methodname>Memcached::fetch</methodname>
+   <modifier>public</modifier> <type>mixed</type><methodname>Memcached::fetch</methodname>
    <void />
   </methodsynopsis>
   <para>
-   The method description goes here.
+   <function>Memcached::fetch</function> retrieves the next result from the
+   last request.
   </para>
  </refsect1>
 
@@ -26,7 +27,9 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Description...
+   Returns the next result or &false; otherwise.
+   The <methodname>Memcached::getResultCode</methodname> will return
+   <constant>Memcached::RES_END</constant> if result set is exhausted.
   </para>
  </refsect1>
 
@@ -38,14 +41,48 @@
     <programlisting role="php">
 <![CDATA[
 <?php
-/* ... */
+$m = new Memcached();
+$m->addServer('localhost', 11211);
+
+$m->set('int', 99);
+$m->set('string', 'a simple string');
+$m->set('array', array(11, 12));
+
+$m->getDelayed(array('int', 'array'), true);
+while ($result = $m->fetch()) {
+    var_dump($result);
+}
 ?>
 ]]>
     </programlisting>
     &example.outputs.similar;
     <screen>
 <![CDATA[
-...
+array(2) {
+  [0]=>
+  array(3) {
+    ["key"]=>
+    string(3) "int"
+    ["value"]=>
+    int(99)
+    ["cas"]=>
+    float(2363)
+  }
+  [1]=>
+  array(3) {
+    ["key"]=>
+    string(5) "array"
+    ["value"]=>
+    array(2) {
+      [0]=>
+      int(11)
+      [1]=>
+      int(12)
+    }
+    ["cas"]=>
+    float(2365)
+  }
+}
 ]]>
     </screen>
    </example>
@@ -56,7 +93,8 @@
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><methodname>Classname::Method</methodname></member>
+    <member><methodname>Memcached::fetchAll</methodname></member>
+    <member><methodname>Memcached::getDelayed</methodname></member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/memcached/memcached/fetchall.xml b/reference/memcached/memcached/fetchall.xml
index ab83e50235..0ae3a54aba 100644
--- a/reference/memcached/memcached/fetchall.xml
+++ b/reference/memcached/memcached/fetchall.xml
@@ -1,20 +1,21 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 
 <refentry xml:id="memcached.fetchall" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::fetchAll</refname>
-  <refpurpose>The fetchAll purpose</refpurpose>
+  <refpurpose>Fetch all the remaining results</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <modifier>public</modifier> <type>void</type><methodname>Memcached::fetchAll</methodname>
+   <modifier>public</modifier> <type>mixed</type><methodname>Memcached::fetchAll</methodname>
    <void />
   </methodsynopsis>
   <para>
-   The method description goes here.
+   <function>Memcached::fetchAll</function> retrieves all the remaining
+   results from the last request.
   </para>
  </refsect1>
 
@@ -26,7 +27,8 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Description...
+   Returns the results or &false; on failure.
+   Use <methodname>Memcached::getResultCode</methodname> if necessary.
   </para>
  </refsect1>
 
@@ -34,18 +36,50 @@
   &reftitle.examples;
   <para>
    <example>
-    <title><function>Memcached::fetchAll</function> example</title>
+    <title><function>Memcached::getDelayed</function> example</title>
     <programlisting role="php">
 <![CDATA[
 <?php
-/* ... */
+$m = new Memcached();
+$m->addServer('localhost', 11211);
+
+$m->set('int', 99);
+$m->set('string', 'a simple string');
+$m->set('array', array(11, 12));
+
+$m->getDelayed(array('int', 'array'), true);
+var_dump($m->fetchAll());
 ?>
 ]]>
     </programlisting>
-    &example.outputs.similar;
+    &example.outputs;
     <screen>
 <![CDATA[
-...
+array(2) {
+  [0]=>
+  array(3) {
+    ["key"]=>
+    string(3) "int"
+    ["value"]=>
+    int(99)
+    ["cas"]=>
+    float(2363)
+  }
+  [1]=>
+  array(3) {
+    ["key"]=>
+    string(5) "array"
+    ["value"]=>
+    array(2) {
+      [0]=>
+      int(11)
+      [1]=>
+      int(12)
+    }
+    ["cas"]=>
+    float(2365)
+  }
+}
 ]]>
     </screen>
    </example>
@@ -56,7 +90,8 @@
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><methodname>Classname::Method</methodname></member>
+    <member><methodname>Memcached::fetch</methodname></member>
+    <member><methodname>Memcached::getDelayed</methodname></member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/memcached/memcached/get.xml b/reference/memcached/memcached/get.xml
index 9036955849..cf9c9f90f8 100644
--- a/reference/memcached/memcached/get.xml
+++ b/reference/memcached/memcached/get.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 
 <refentry xml:id="memcached.get" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -22,7 +22,7 @@
    CAS token value for the item. See
    <methodname>Memcached::cas</methodname> for how to use CAS tokens. <link
     linkend="memcached.callbacks">Read-through caching callback</link> may be
-   specified via <parameter>cache_cb</parameter>.
+   specified via <parameter>cache_cb</parameter> parameter.
   </para>
   <para>
   </para>
@@ -44,7 +44,7 @@
      <term><parameter>cache_cb</parameter></term>
      <listitem>
       <para>
-       Read-through caching callback or &null;
+       Read-through caching callback or &null;.
       </para>
      </listitem>
     </varlistentry>
@@ -63,7 +63,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Returns the value stored in the cache or &false; on failure.
+   Returns the value stored in the cache or &false; otherwise.
    The <methodname>Memcached::getResultCode</methodname> will return
    <constant>Memcached::RES_NOTFOUND</constant> if the key does not exist.
   </para>
diff --git a/reference/memcached/memcached/getbykey.xml b/reference/memcached/memcached/getbykey.xml
index 814e52642b..07c6c96b1c 100644
--- a/reference/memcached/memcached/getbykey.xml
+++ b/reference/memcached/memcached/getbykey.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 
 <refentry xml:id="memcached.getbykey" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -67,7 +67,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Returns the value stored in the cache or &false; on failure.
+   Returns the value stored in the cache or &false; otherwise.
    The <methodname>Memcached::getResultCode</methodname> will return
    <constant>Memcached::RES_NOTFOUND</constant> if the key does not exist.
   </para>
diff --git a/reference/memcached/memcached/getdelayed.xml b/reference/memcached/memcached/getdelayed.xml
index 2fabeb12d6..1366b77611 100644
--- a/reference/memcached/memcached/getdelayed.xml
+++ b/reference/memcached/memcached/getdelayed.xml
@@ -1,22 +1,33 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 
 <refentry xml:id="memcached.getdelayed" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::getDelayed</refname>
-  <refpurpose>The getDelayed purpose</refpurpose>
+  <refpurpose>Request multiple items</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <modifier>public</modifier> <type>void</type><methodname>Memcached::getDelayed</methodname>
+   <modifier>public</modifier> <type>bool</type><methodname>Memcached::getDelayed</methodname>
    <methodparam><type>array</type><parameter>keys</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>with_cas</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>value_cb</parameter></methodparam>
+   <methodparam choice="opt"><type>bool</type><parameter>with_cas</parameter></methodparam>
+   <methodparam choice="opt"><type>callback</type><parameter>value_cb</parameter></methodparam>
   </methodsynopsis>
   <para>
-   The method description goes here.
+   <function>Memcached::getDelayed</function> issues a request to memcache for
+   multiple items the keys of which are specified in the
+   <parameter>keys</parameter> array. The method does not wait for response
+   and returns right away. When you are ready to collect the items, call
+   either <methodname>Memcached::fetch</methodname> or
+   <methodname>Memcached::fetchAll</methodname>. If <parameter>with_cas</parameter>
+   is true, the CAS token values will also be requested.
+  </para>
+  <para>
+   Instead of fetching the results explicitly, you can specify a <link
+    linkend="memcached.callbacks">result callback</link> via
+   <parameter>value_cb</parameter> parameter.
   </para>
  </refsect1>
 
@@ -28,7 +39,7 @@
      <term><parameter>keys</parameter></term>
      <listitem>
       <para>
-       Description...
+       Array of keys to request.
       </para>
      </listitem>
     </varlistentry>
@@ -36,7 +47,7 @@
      <term><parameter>with_cas</parameter></term>
      <listitem>
       <para>
-       Description...
+       Whether to request CAS token values also.
       </para>
      </listitem>
     </varlistentry>
@@ -44,7 +55,7 @@
      <term><parameter>value_cb</parameter></term>
      <listitem>
       <para>
-       Description...
+       The result callback or &null;.
       </para>
      </listitem>
     </varlistentry>
@@ -55,7 +66,8 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Description...
+   &return.success;
+   Use <methodname>Memcached::getResultCode</methodname> if necessary.
   </para>
  </refsect1>
 
@@ -67,14 +79,46 @@
     <programlisting role="php">
 <![CDATA[
 <?php
-/* ... */
+$m = new Memcached();
+$m->addServer('localhost', 11211);
+
+$m->set('int', 99);
+$m->set('string', 'a simple string');
+$m->set('array', array(11, 12));
+
+$m->getDelayed(array('int', 'array'), true);
+var_dump($m->fetchAll());
 ?>
 ]]>
     </programlisting>
-    &example.outputs.similar;
+    &example.outputs;
     <screen>
 <![CDATA[
-...
+array(2) {
+  [0]=>
+  array(3) {
+    ["key"]=>
+    string(3) "int"
+    ["value"]=>
+    int(99)
+    ["cas"]=>
+    float(2363)
+  }
+  [1]=>
+  array(3) {
+    ["key"]=>
+    string(5) "array"
+    ["value"]=>
+    array(2) {
+      [0]=>
+      int(11)
+      [1]=>
+      int(12)
+    }
+    ["cas"]=>
+    float(2365)
+  }
+}
 ]]>
     </screen>
    </example>
@@ -85,7 +129,9 @@
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><methodname>Classname::Method</methodname></member>
+    <member><methodname>Memcached::getDelayedByKey</methodname></member>
+    <member><methodname>Memcached::fetch</methodname></member>
+    <member><methodname>Memcached::fetchAll</methodname></member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/memcached/memcached/getdelayedbykey.xml b/reference/memcached/memcached/getdelayedbykey.xml
index b9875f8e27..418e361a47 100644
--- a/reference/memcached/memcached/getdelayedbykey.xml
+++ b/reference/memcached/memcached/getdelayedbykey.xml
@@ -1,23 +1,26 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 
 <refentry xml:id="memcached.getdelayedbykey" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::getDelayedByKey</refname>
-  <refpurpose>The getDelayedByKey purpose</refpurpose>
+  <refpurpose>Request multiple items from a specific server</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <modifier>public</modifier> <type>void</type><methodname>Memcached::getDelayedByKey</methodname>
+   <modifier>public</modifier> <type>bool</type><methodname>Memcached::getDelayedByKey</methodname>
    <methodparam><type>string</type><parameter>server_key</parameter></methodparam>
    <methodparam><type>array</type><parameter>keys</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>with_cas</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>value_cb</parameter></methodparam>
+   <methodparam choice="opt"><type>bool</type><parameter>with_cas</parameter></methodparam>
+   <methodparam choice="opt"><type>callback</type><parameter>value_cb</parameter></methodparam>
   </methodsynopsis>
   <para>
-   The method description goes here.
+   <function>Memcached::getDelayedByKey</function> is functionally equivalent to
+   <methodname>Memcached::getDelayed</methodname>, except that the free-form
+   <parameter>server_key</parameter> can be used to map the
+   <parameter>keys</parameter> to a specific server.
   </para>
  </refsect1>
 
@@ -29,7 +32,7 @@
      <term><parameter>server_key</parameter></term>
      <listitem>
       <para>
-       Description...
+       The key identifying the server to request the items from.
       </para>
      </listitem>
     </varlistentry>
@@ -37,7 +40,7 @@
      <term><parameter>keys</parameter></term>
      <listitem>
       <para>
-       Description...
+       Array of keys to request.
       </para>
      </listitem>
     </varlistentry>
@@ -45,7 +48,7 @@
      <term><parameter>with_cas</parameter></term>
      <listitem>
       <para>
-       Description...
+       Whether to request CAS token values also.
       </para>
      </listitem>
     </varlistentry>
@@ -53,7 +56,7 @@
      <term><parameter>value_cb</parameter></term>
      <listitem>
       <para>
-       Description...
+       The result callback or &null;.
       </para>
      </listitem>
     </varlistentry>
@@ -64,29 +67,8 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Description...
-  </para>
- </refsect1>
-
- <refsect1 role="examples">
-  &reftitle.examples;
-  <para>
-   <example>
-    <title><function>Memcached::getDelayedByKey</function> example</title>
-    <programlisting role="php">
-<![CDATA[
-<?php
-/* ... */
-?>
-]]>
-    </programlisting>
-    &example.outputs.similar;
-    <screen>
-<![CDATA[
-...
-]]>
-    </screen>
-   </example>
+   &return.success;
+   Use <methodname>Memcached::getResultCode</methodname> if necessary.
   </para>
  </refsect1>
 
@@ -94,7 +76,9 @@
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><methodname>Classname::Method</methodname></member>
+    <member><methodname>Memcached::getDelayed</methodname></member>
+    <member><methodname>Memcached::fetch</methodname></member>
+    <member><methodname>Memcached::fetchAll</methodname></member>
    </simplelist>
   </para>
  </refsect1>