From 0d95fa323ae23175b8e44b98f06cb78fba06ab07 Mon Sep 17 00:00:00 2001
From: Andrei Zmievski <andrei@php.net>
Date: Wed, 4 Feb 2009 23:57:16 +0000
Subject: [PATCH] Document get* and getMulti* methods.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@275194 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/memcached/memcached/get.xml         | 67 ++++++++++++++-----
 reference/memcached/memcached/getbykey.xml    | 53 ++++++---------
 reference/memcached/memcached/getmulti.xml    | 58 +++++++++++++---
 .../memcached/memcached/getmultibykey.xml     | 44 ++++--------
 4 files changed, 132 insertions(+), 90 deletions(-)

diff --git a/reference/memcached/memcached/get.xml b/reference/memcached/memcached/get.xml
index 943023dbfd..9036955849 100644
--- a/reference/memcached/memcached/get.xml
+++ b/reference/memcached/memcached/get.xml
@@ -1,22 +1,30 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 
 <refentry xml:id="memcached.get" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::get</refname>
-  <refpurpose>The get purpose</refpurpose>
+  <refpurpose>Retrieve an item</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <modifier>public</modifier> <type>void</type><methodname>Memcached::get</methodname>
+   <modifier>public</modifier> <type>mixed</type><methodname>Memcached::get</methodname>
    <methodparam><type>string</type><parameter>key</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>cache_cb</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter role="reference">cas_token</parameter></methodparam>
+   <methodparam choice="opt"><type>callback</type><parameter>cache_cb</parameter></methodparam>
+   <methodparam choice="opt"><type>double</type><parameter role="reference">cas_token</parameter></methodparam>
   </methodsynopsis>
   <para>
-   The method description goes here.
+   <function>Memcached::get</function> returns the item that was previously
+   stored under the <parameter>key</parameter>. If the item is found and
+   <parameter>cas_token</parameter> variable is provided, it will contain the
+   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>.
+  </para>
+  <para>
   </para>
  </refsect1>
 
@@ -28,7 +36,7 @@
      <term><parameter>key</parameter></term>
      <listitem>
       <para>
-       Description...
+       The key of the item to retrieve.
       </para>
      </listitem>
     </varlistentry>
@@ -36,7 +44,7 @@
      <term><parameter>cache_cb</parameter></term>
      <listitem>
       <para>
-       Description...
+       Read-through caching callback or &null;
       </para>
      </listitem>
     </varlistentry>
@@ -44,7 +52,7 @@
      <term><parameter>cas_token</parameter></term>
      <listitem>
       <para>
-       Description...
+       The variable to store the CAS token in.
       </para>
      </listitem>
     </varlistentry>
@@ -55,7 +63,9 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Description...
+   Returns the value stored in the cache or &false; on failure.
+   The <methodname>Memcached::getResultCode</methodname> will return
+   <constant>Memcached::RES_NOTFOUND</constant> if the key does not exist.
   </para>
  </refsect1>
 
@@ -63,21 +73,46 @@
   &reftitle.examples;
   <para>
    <example>
-    <title><function>Memcached::get</function> example</title>
+    <title><function>Memcached::get</function> example #1</title>
     <programlisting role="php">
 <![CDATA[
 <?php
-/* ... */
+$m = new Memcached();
+$m->addServer('localhost', 11211);
+
+$m->set('foo', 100);
+var_dump($m->get('foo'));
 ?>
 ]]>
     </programlisting>
-    &example.outputs.similar;
+    &example.outputs;
     <screen>
 <![CDATA[
-...
+int(100)
 ]]>
     </screen>
    </example>
+   <example>
+    <title><function>Memcached::get</function> example #2</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$m = new Memcached();
+$m->addServer('localhost', 11211);
+
+if (!($ip = $m->get('ip_block'))) {
+    if ($m->getResultCode() == Memcached::RES_NOTFOUND) {
+        $ip = array();
+        $m->set('ip_block', $ip);
+    } else {
+        /* log error */
+        ...
+    }
+}
+?>
+]]>
+    </programlisting>
+   </example>
   </para>
  </refsect1>
 
@@ -85,7 +120,9 @@
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><methodname>Classname::Method</methodname></member>
+    <member><methodname>Memcached::getByKey</methodname></member>
+    <member><methodname>Memcached::getMulti</methodname></member>
+    <member><methodname>Memcached::getDelayed</methodname></member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/memcached/memcached/getbykey.xml b/reference/memcached/memcached/getbykey.xml
index 91d635cd30..814e52642b 100644
--- a/reference/memcached/memcached/getbykey.xml
+++ b/reference/memcached/memcached/getbykey.xml
@@ -1,23 +1,26 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 
 <refentry xml:id="memcached.getbykey" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::getByKey</refname>
-  <refpurpose>The getByKey purpose</refpurpose>
+  <refpurpose>Retrieve an item from a specific server</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <modifier>public</modifier> <type>void</type><methodname>Memcached::getByKey</methodname>
+   <modifier>public</modifier> <type>mixed</type><methodname>Memcached::getByKey</methodname>
    <methodparam><type>string</type><parameter>server_key</parameter></methodparam>
    <methodparam><type>string</type><parameter>key</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>cache_cb</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter role="reference">cas_token</parameter></methodparam>
+   <methodparam choice="opt"><type>callback</type><parameter>cache_cb</parameter></methodparam>
+   <methodparam choice="opt"><type>double</type><parameter role="reference">cas_token</parameter></methodparam>
   </methodsynopsis>
   <para>
-   The method description goes here.
+   <function>Memcached::getByKey</function> is functionally equivalent to
+   <methodname>Memcached::get</methodname>, except that the free-form
+   <parameter>server_key</parameter> can be used to map the
+   <parameter>key</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 fetch the item from.
       </para>
      </listitem>
     </varlistentry>
@@ -37,7 +40,7 @@
      <term><parameter>key</parameter></term>
      <listitem>
       <para>
-       Description...
+       The key of the item to fetch.
       </para>
      </listitem>
     </varlistentry>
@@ -45,7 +48,7 @@
      <term><parameter>cache_cb</parameter></term>
      <listitem>
       <para>
-       Description...
+       Read-through caching callback or &null;
       </para>
      </listitem>
     </varlistentry>
@@ -53,7 +56,7 @@
      <term><parameter>cas_token</parameter></term>
      <listitem>
       <para>
-       Description...
+       The variable to store the CAS token in.
       </para>
      </listitem>
     </varlistentry>
@@ -64,29 +67,9 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Description...
-  </para>
- </refsect1>
-
- <refsect1 role="examples">
-  &reftitle.examples;
-  <para>
-   <example>
-    <title><function>Memcached::getByKey</function> example</title>
-    <programlisting role="php">
-<![CDATA[
-<?php
-/* ... */
-?>
-]]>
-    </programlisting>
-    &example.outputs.similar;
-    <screen>
-<![CDATA[
-...
-]]>
-    </screen>
-   </example>
+   Returns the value stored in the cache or &false; on failure.
+   The <methodname>Memcached::getResultCode</methodname> will return
+   <constant>Memcached::RES_NOTFOUND</constant> if the key does not exist.
   </para>
  </refsect1>
 
@@ -94,7 +77,9 @@
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><methodname>Classname::Method</methodname></member>
+    <member><methodname>Memcached::get</methodname></member>
+    <member><methodname>Memcached::getMulti</methodname></member>
+    <member><methodname>Memcached::getDelayed</methodname></member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/memcached/memcached/getmulti.xml b/reference/memcached/memcached/getmulti.xml
index d75638bfa1..fd87d8f178 100644
--- a/reference/memcached/memcached/getmulti.xml
+++ b/reference/memcached/memcached/getmulti.xml
@@ -1,21 +1,33 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 
 <refentry xml:id="memcached.getmulti" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::getMulti</refname>
-  <refpurpose>The getMulti purpose</refpurpose>
+  <refpurpose>Retrieve multiple items</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <modifier>public</modifier> <type>void</type><methodname>Memcached::getMulti</methodname>
+   <modifier>public</modifier> <type>mixed</type><methodname>Memcached::getMulti</methodname>
    <methodparam><type>array</type><parameter>keys</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter role="reference">cas_tokens</parameter></methodparam>
+   <methodparam choice="opt"><type>array</type><parameter role="reference">cas_tokens</parameter></methodparam>
   </methodsynopsis>
   <para>
-   The method description goes here.
+   <function>Memcached::getMulti</function> is similar to
+   <methodname>Memcached::get</methodname>, but instead of a single key
+   item, it retrievess multiple items the keys of which are specified in the
+   <parameter>keys</parameter> array. If <parameter>cas_tokens</parameter>
+   variable is provided, it is filled with the CAS token values for the found
+   items.
+   <note>
+    Unlike <methodname>Memcached::get</methodname> it is not possible to
+    specify a read-through cache callback for
+    <function>Memcached::getMulti</function>, because the memcache protocol
+    does provide information on which keys were not found in the multi-key
+    request.
+   </note>
   </para>
  </refsect1>
 
@@ -27,7 +39,7 @@
      <term><parameter>keys</parameter></term>
      <listitem>
       <para>
-       Description...
+       Array of keys to retrieve.
       </para>
      </listitem>
     </varlistentry>
@@ -35,7 +47,7 @@
      <term><parameter>cas_tokens</parameter></term>
      <listitem>
       <para>
-       Description...
+       The variable to store the CAS tokens for the found items.
       </para>
      </listitem>
     </varlistentry>
@@ -46,7 +58,8 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Description...
+   Returns the array of found items or &false; on failure.
+   Use <methodname>Memcached::getResultCode</methodname> if necessary.
   </para>
  </refsect1>
 
@@ -58,14 +71,35 @@
     <programlisting role="php">
 <![CDATA[
 <?php
-/* ... */
+$m = new Memcached();
+$m->addServer('localhost', 11211);
+
+$items = array(
+    'key1' => 'value1',
+    'key2' => 'value2',
+    'key3' => 'value3'
+);
+$m->setMulti($items);
+$result = $m->getMulti(array('key1', 'key3', 'badkey'), $cas);
+var_dump($result, $cas);
 ?>
 ]]>
     </programlisting>
     &example.outputs.similar;
     <screen>
 <![CDATA[
-...
+array(2) {
+  ["key1"]=>
+  string(6) "value1"
+  ["key3"]=>
+  string(6) "value3"
+}
+array(2) {
+  ["key1"]=>
+  float(2360)
+  ["key3"]=>
+  float(2362)
+}
 ]]>
     </screen>
    </example>
@@ -76,7 +110,9 @@
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><methodname>Classname::Method</methodname></member>
+    <member><methodname>Memcached::getMultiByKey</methodname></member>
+    <member><methodname>Memcached::get</methodname></member>
+    <member><methodname>Memcached::getDelayed</methodname></member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/memcached/memcached/getmultibykey.xml b/reference/memcached/memcached/getmultibykey.xml
index a2a7934ede..e2de0448e3 100644
--- a/reference/memcached/memcached/getmultibykey.xml
+++ b/reference/memcached/memcached/getmultibykey.xml
@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 
 <refentry xml:id="memcached.getmultibykey" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::getMultiByKey</refname>
-  <refpurpose>The getMultiByKey purpose</refpurpose>
+  <refpurpose>Retrieve multiple items from a specific server</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -16,7 +16,10 @@
    <methodparam choice="opt"><type>string</type><parameter role="reference">cas_tokens</parameter></methodparam>
   </methodsynopsis>
   <para>
-   The method description goes here.
+   <function>Memcached::getMultiByKey</function> is functionally equivalent to
+   <methodname>Memcached::getMulti</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>
 
@@ -28,7 +31,7 @@
      <term><parameter>server_key</parameter></term>
      <listitem>
       <para>
-       Description...
+       The key identifying the server to fetch the items from.
       </para>
      </listitem>
     </varlistentry>
@@ -36,7 +39,7 @@
      <term><parameter>keys</parameter></term>
      <listitem>
       <para>
-       Description...
+       Array of keys to retrieve.
       </para>
      </listitem>
     </varlistentry>
@@ -44,7 +47,7 @@
      <term><parameter>cas_tokens</parameter></term>
      <listitem>
       <para>
-       Description...
+       The variable to store the CAS tokens for the found items.
       </para>
      </listitem>
     </varlistentry>
@@ -55,29 +58,8 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Description...
-  </para>
- </refsect1>
-
- <refsect1 role="examples">
-  &reftitle.examples;
-  <para>
-   <example>
-    <title><function>Memcached::getMultiByKey</function> example</title>
-    <programlisting role="php">
-<![CDATA[
-<?php
-/* ... */
-?>
-]]>
-    </programlisting>
-    &example.outputs.similar;
-    <screen>
-<![CDATA[
-...
-]]>
-    </screen>
-   </example>
+   Returns the array of found items or &false; on failure.
+   Use <methodname>Memcached::getResultCode</methodname> if necessary.
   </para>
  </refsect1>
 
@@ -85,7 +67,9 @@
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><methodname>Classname::Method</methodname></member>
+    <member><methodname>Memcached::getMulti</methodname></member>
+    <member><methodname>Memcached::get</methodname></member>
+    <member><methodname>Memcached::getDelayed</methodname></member>
    </simplelist>
   </para>
  </refsect1>