From 9918e9e6cece3764fae4ef8d1d1c5de04d31fe97 Mon Sep 17 00:00:00 2001
From: Andrei Zmievski <andrei@php.net>
Date: Tue, 3 Feb 2009 22:43:50 +0000
Subject: [PATCH] - Document increment/decrement - Fix up stuff.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@275152 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/memcached/memcached/add.xml         |  4 +-
 reference/memcached/memcached/addbykey.xml    |  4 +-
 reference/memcached/memcached/construct.xml   |  5 +--
 reference/memcached/memcached/decrement.xml   | 40 +++++++++++++------
 reference/memcached/memcached/increment.xml   | 40 +++++++++++++------
 reference/memcached/memcached/replace.xml     |  4 +-
 .../memcached/memcached/replacebykey.xml      |  4 +-
 reference/memcached/memcached/set.xml         |  4 +-
 reference/memcached/memcached/setbykey.xml    |  4 +-
 reference/memcached/memcached/setmulti.xml    | 18 ++++-----
 .../memcached/memcached/setmultibykey.xml     | 10 ++---
 11 files changed, 84 insertions(+), 53 deletions(-)

diff --git a/reference/memcached/memcached/add.xml b/reference/memcached/memcached/add.xml
index a23a2e372e..5fe84ad064 100644
--- a/reference/memcached/memcached/add.xml
+++ b/reference/memcached/memcached/add.xml
@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 
 <refentry xml:id="memcached.add" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::add</refname>
-  <refpurpose>Add data under a new key</refpurpose>
+  <refpurpose>Add an item under a new key</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
diff --git a/reference/memcached/memcached/addbykey.xml b/reference/memcached/memcached/addbykey.xml
index e0c6c65e91..f8ed1defd3 100644
--- a/reference/memcached/memcached/addbykey.xml
+++ b/reference/memcached/memcached/addbykey.xml
@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 
 <refentry xml:id="memcached.addbykey" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::addByKey</refname>
-  <refpurpose>Add data under a new key on a specific server</refpurpose>
+  <refpurpose>Add an item under a new key on a specific server</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
diff --git a/reference/memcached/memcached/construct.xml b/reference/memcached/memcached/construct.xml
index 52fb22dc99..be0081b6be 100644
--- a/reference/memcached/memcached/construct.xml
+++ b/reference/memcached/memcached/construct.xml
@@ -1,11 +1,10 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 
 <refentry xml:id="memcached.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::__construct</refname>
-  <refpurpose>Creates a Memcached instance representing the connection to the
-   memcache servers</refpurpose>
+  <refpurpose>Create a Memcached instance</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
diff --git a/reference/memcached/memcached/decrement.xml b/reference/memcached/memcached/decrement.xml
index b97ab1dc4a..97762af22a 100644
--- a/reference/memcached/memcached/decrement.xml
+++ b/reference/memcached/memcached/decrement.xml
@@ -1,21 +1,26 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 
 <refentry xml:id="memcached.decrement" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::decrement</refname>
-  <refpurpose>The decrement purpose</refpurpose>
+  <refpurpose>Decrement numeric item's value</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <modifier>public</modifier> <type>void</type><methodname>Memcached::decrement</methodname>
+   <modifier>public</modifier> <type>bool</type><methodname>Memcached::decrement</methodname>
    <methodparam><type>string</type><parameter>key</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>offset</parameter></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>offset</parameter></methodparam>
   </methodsynopsis>
   <para>
-   The method description goes here.
+   <function>Memcached::decrement</function> decrements a numeric item's value
+   by the specified <parameter>offset</parameter>. If the item's value is not
+   numeric, it is treated as if the value were 0. If the operation would
+   decrease the value below 0, the new value will be 0.
+   <function>Memcached::decrement</function> will fail if the item does not
+   exist.
   </para>
  </refsect1>
 
@@ -27,7 +32,7 @@
      <term><parameter>key</parameter></term>
      <listitem>
       <para>
-       Description...
+       The key of the item to decrement.
       </para>
      </listitem>
     </varlistentry>
@@ -35,7 +40,7 @@
      <term><parameter>offset</parameter></term>
      <listitem>
       <para>
-       Description...
+       The amount by which to decrement the item's value; defaults to 1.
       </para>
      </listitem>
     </varlistentry>
@@ -46,7 +51,9 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Description...
+   &return.success;
+   The <methodname>Memcached::getResultCode</methodname> will return
+   <constant>Memcached::RES_NOTFOUND</constant> if the key does not exist.
   </para>
  </refsect1>
 
@@ -58,14 +65,23 @@
     <programlisting role="php">
 <![CDATA[
 <?php
-/* ... */
+$m = new Memcached();
+$m->addServer('localhost', 11211);
+
+$m->set('counter', 5);
+$m->decrement('counter');
+var_dump($m->get('counter'));
+
+$m->decrement('counter', 10);
+var_dump($m->get('counter'));
 ?>
 ]]>
     </programlisting>
-    &example.outputs.similar;
+    &example.outputs;
     <screen>
 <![CDATA[
-...
+int(4)
+int(0)
 ]]>
     </screen>
    </example>
@@ -76,7 +92,7 @@
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><methodname>Classname::Method</methodname></member>
+    <member><methodname>Memcached::increment</methodname></member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/memcached/memcached/increment.xml b/reference/memcached/memcached/increment.xml
index 3691549b6b..f5ad90f84d 100644
--- a/reference/memcached/memcached/increment.xml
+++ b/reference/memcached/memcached/increment.xml
@@ -1,21 +1,25 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 
 <refentry xml:id="memcached.increment" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::increment</refname>
-  <refpurpose>The increment purpose</refpurpose>
+  <refpurpose>Increment numeric item's value</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <modifier>public</modifier> <type>void</type><methodname>Memcached::increment</methodname>
+   <modifier>public</modifier> <type>bool</type><methodname>Memcached::increment</methodname>
    <methodparam><type>string</type><parameter>key</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>offset</parameter></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>offset</parameter></methodparam>
   </methodsynopsis>
   <para>
-   The method description goes here.
+   <function>Memcached::increment</function> increments a numeric item's value
+   by the specified <parameter>offset</parameter>. If the item's value is not
+   numeric, it is treated as if the value were 0.
+   <function>Memcached::increment</function> will fail if the item does not
+   exist.
   </para>
  </refsect1>
 
@@ -27,7 +31,7 @@
      <term><parameter>key</parameter></term>
      <listitem>
       <para>
-       Description...
+       The key of the item to increment.
       </para>
      </listitem>
     </varlistentry>
@@ -35,7 +39,7 @@
      <term><parameter>offset</parameter></term>
      <listitem>
       <para>
-       Description...
+       The amount by which to increment the item's value; defaults to 1.
       </para>
      </listitem>
     </varlistentry>
@@ -46,7 +50,9 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Description...
+   &return.success;
+   The <methodname>Memcached::getResultCode</methodname> will return
+   <constant>Memcached::RES_NOTFOUND</constant> if the key does not exist.
   </para>
  </refsect1>
 
@@ -58,14 +64,24 @@
     <programlisting role="php">
 <![CDATA[
 <?php
-/* ... */
+$m = new Memcached();
+$m->addServer('localhost', 11211);
+
+$m->set('counter', 0);
+$m->increment('counter');
+$m->increment('counter', 10);
+var_dump($m->get('counter'));
+
+$m->set('key', 'abc');
+$m->increment('counter');
 ?>
 ]]>
     </programlisting>
-    &example.outputs.similar;
+    &example.outputs;
     <screen>
 <![CDATA[
-...
+int(11)
+string(1) "1"
 ]]>
     </screen>
    </example>
@@ -76,7 +92,7 @@
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><methodname>Classname::Method</methodname></member>
+    <member><methodname>Memcached::decrement</methodname></member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/memcached/memcached/replace.xml b/reference/memcached/memcached/replace.xml
index d0f6e772bf..a77281bc14 100644
--- a/reference/memcached/memcached/replace.xml
+++ b/reference/memcached/memcached/replace.xml
@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 
 <refentry xml:id="memcached.replace" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::replace</refname>
-  <refpurpose>Replace data under an existing key</refpurpose>
+  <refpurpose>Replace the item under an existing key</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
diff --git a/reference/memcached/memcached/replacebykey.xml b/reference/memcached/memcached/replacebykey.xml
index 550a325290..f63a30c165 100644
--- a/reference/memcached/memcached/replacebykey.xml
+++ b/reference/memcached/memcached/replacebykey.xml
@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 
 <refentry xml:id="memcached.replacebykey" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::replaceByKey</refname>
-  <refpurpose>Replace data under an existing key on a specific server</refpurpose>
+  <refpurpose>Replace the item under an existing key on a specific server</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
diff --git a/reference/memcached/memcached/set.xml b/reference/memcached/memcached/set.xml
index ddcc9daa5d..3b18bebf23 100644
--- a/reference/memcached/memcached/set.xml
+++ b/reference/memcached/memcached/set.xml
@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 
 <refentry xml:id="memcached.set" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::set</refname>
-  <refpurpose>Store data under a key</refpurpose>
+  <refpurpose>Store an item</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
diff --git a/reference/memcached/memcached/setbykey.xml b/reference/memcached/memcached/setbykey.xml
index 9f2122c6d7..6bc698cc9a 100644
--- a/reference/memcached/memcached/setbykey.xml
+++ b/reference/memcached/memcached/setbykey.xml
@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 
 <refentry xml:id="memcached.setbykey" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::setByKey</refname>
-  <refpurpose>Store data under a key on a specific server</refpurpose>
+  <refpurpose>Store an item on a specific server</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
diff --git a/reference/memcached/memcached/setmulti.xml b/reference/memcached/memcached/setmulti.xml
index 3a5e54d174..8716f1b3dd 100644
--- a/reference/memcached/memcached/setmulti.xml
+++ b/reference/memcached/memcached/setmulti.xml
@@ -1,25 +1,25 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 
 <refentry xml:id="memcached.setmulti" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::setMulti</refname>
-  <refpurpose>Store multiple sets of data</refpurpose>
+  <refpurpose>Store multiple items</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
    <modifier>public</modifier> <type>bool</type><methodname>Memcached::setMulti</methodname>
-   <methodparam><type>array</type><parameter>entries</parameter></methodparam>
+   <methodparam><type>array</type><parameter>items</parameter></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>expiration</parameter></methodparam>
   </methodsynopsis>
   <para>
    <function>Memcached::setMulti</function> is similar to
    <methodname>Memcached::set</methodname>, but instead of a single key/value
-   pair, it works on multiple sets specified in
-   <parameter>entries</parameter>. The <parameter>expiration</parameter>
-   time applies to all the entries at once.
+   item, it works on multiple items specified in
+   <parameter>items</parameter>. The <parameter>expiration</parameter> time
+   applies to all the items at once.
   </para>
  </refsect1>
 
@@ -28,7 +28,7 @@
   <para>
    <variablelist>
     <varlistentry>
-     <term><parameter>entries</parameter></term>
+     <term><parameter>items</parameter></term>
      <listitem>
       <para>
        An array of key/value pairs to store on the server.
@@ -67,12 +67,12 @@
 $m = new Memcached();
 $m->addServer('localhost', 11211);
 
-$entries = array(
+$items = array(
     'key1' => 'value1',
     'key2' => 'value2',
     'key3' => 'value3'
 );
-$m->set($entries, time() + 300);
+$m->set($items, time() + 300);
 ?>
 ]]>
     </programlisting>
diff --git a/reference/memcached/memcached/setmultibykey.xml b/reference/memcached/memcached/setmultibykey.xml
index d85e80c53f..bb806c6dda 100644
--- a/reference/memcached/memcached/setmultibykey.xml
+++ b/reference/memcached/memcached/setmultibykey.xml
@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 
 <refentry xml:id="memcached.setmultibykey" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::setMultiByKey</refname>
-  <refpurpose>Store multiple sets of data on a specific server</refpurpose>
+  <refpurpose>Store multiple items on a specific server</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -12,14 +12,14 @@
   <methodsynopsis>
    <modifier>public</modifier> <type>bool</type><methodname>Memcached::setMultiByKey</methodname>
    <methodparam><type>string</type><parameter>server_key</parameter></methodparam>
-   <methodparam><type>array</type><parameter>entries</parameter></methodparam>
+   <methodparam><type>array</type><parameter>items</parameter></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>expiration</parameter></methodparam>
   </methodsynopsis>
   <para>
    <function>Memcached::setMultiByKey</function> is functionally equivalent to
    <methodname>Memcached::setMulti</methodname>, except that the free-form
    <parameter>server_key</parameter> can be used to map the keys from
-   <parameter>entries</parameter> to a specific server. This is useful if you
+   <parameter>items</parameter> to a specific server. This is useful if you
    need to keep a bunch of related keys on a certain server.
   </para>
  </refsect1>
@@ -37,7 +37,7 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><parameter>entries</parameter></term>
+     <term><parameter>items</parameter></term>
      <listitem>
       <para>
        An array of key/value pairs to store on the server.