From 942b923fb40701e34bcac494c1762bc52ed11424 Mon Sep 17 00:00:00 2001
From: Andrei Zmievski <andrei@php.net>
Date: Wed, 4 Feb 2009 00:19:34 +0000
Subject: [PATCH] Document append* and prepend* methods.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@275155 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/memcached/memcached/append.xml      | 51 ++++++++++-------
 reference/memcached/memcached/appendbykey.xml | 55 +++++--------------
 reference/memcached/memcached/prepend.xml     | 51 ++++++++++-------
 .../memcached/memcached/prependbykey.xml      | 55 +++++--------------
 4 files changed, 92 insertions(+), 120 deletions(-)

diff --git a/reference/memcached/memcached/append.xml b/reference/memcached/memcached/append.xml
index 33269bd988..2b45b8270a 100644
--- a/reference/memcached/memcached/append.xml
+++ b/reference/memcached/memcached/append.xml
@@ -1,23 +1,33 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 
 <refentry xml:id="memcached.append" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::append</refname>
-  <refpurpose>The append purpose</refpurpose>
+  <refpurpose>Append data to an existing item</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <modifier>public</modifier> <type>void</type><methodname>Memcached::append</methodname>
+   <modifier>public</modifier> <type>bool</type><methodname>Memcached::append</methodname>
    <methodparam><type>string</type><parameter>key</parameter></methodparam>
    <methodparam><type>string</type><parameter>value</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>expiration</parameter></methodparam>
   </methodsynopsis>
   <para>
-   The method description goes here.
+   <function>Memcached::append</function> appends the given
+   <parameter>value</parameter> string to the value of an existing item. The
+   reason that <parameter>value</parameter> is forced to be a string is
+   that appending mixed types is not well-defined.
   </para>
+  <note>
+   <para>
+    If the <constant>Memcached::OPT_COMPRESSION</constant> is enabled, the
+    operation will fail and a warning will be issued, because appending
+    compressed data to a value that is potentially already compressed is not
+    possible.
+   </para>
+  </note>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -28,7 +38,7 @@
      <term><parameter>key</parameter></term>
      <listitem>
       <para>
-       Description...
+       The key of the item to append the data to.
       </para>
      </listitem>
     </varlistentry>
@@ -36,15 +46,7 @@
      <term><parameter>value</parameter></term>
      <listitem>
       <para>
-       Description...
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term><parameter>expiration</parameter></term>
-     <listitem>
-      <para>
-       Description...
+       The string to append.
       </para>
      </listitem>
     </varlistentry>
@@ -55,7 +57,9 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Description...
+   &return.success;
+   The <methodname>Memcached::getResultCode</methodname> will return
+   <constant>Memcached::RES_NOTSTORED</constant> if the key does not exist.
   </para>
  </refsect1>
 
@@ -67,14 +71,20 @@
     <programlisting role="php">
 <![CDATA[
 <?php
-/* ... */
+$m = new Memcached();
+$m->addServer('localhost', 11211);
+$m->setOption(Memcached::OPT_COMPRESSION, false);
+
+$m->set('foo', 'abc');
+$m->append('foo', 'def');
+var_dump($m->get('foo'));
 ?>
 ]]>
     </programlisting>
-    &example.outputs.similar;
+    &example.outputs;
     <screen>
 <![CDATA[
-...
+string(6) "abcdef"
 ]]>
     </screen>
    </example>
@@ -85,7 +95,8 @@
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><methodname>Classname::Method</methodname></member>
+    <member><methodname>Memcached::appendByKey</methodname></member>
+    <member><methodname>Memcached::prepend</methodname></member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/memcached/memcached/appendbykey.xml b/reference/memcached/memcached/appendbykey.xml
index 74a49ee9d9..e8020b49de 100644
--- a/reference/memcached/memcached/appendbykey.xml
+++ b/reference/memcached/memcached/appendbykey.xml
@@ -1,23 +1,25 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 
 <refentry xml:id="memcached.appendbykey" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::appendByKey</refname>
-  <refpurpose>The appendByKey purpose</refpurpose>
+  <refpurpose>Append data to an existing item on a specific server</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <modifier>public</modifier> <type>void</type><methodname>Memcached::appendByKey</methodname>
+   <modifier>public</modifier> <type>bool</type><methodname>Memcached::appendByKey</methodname>
    <methodparam><type>string</type><parameter>server_key</parameter></methodparam>
    <methodparam><type>string</type><parameter>key</parameter></methodparam>
    <methodparam><type>string</type><parameter>value</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>expiration</parameter></methodparam>
   </methodsynopsis>
   <para>
-   The method description goes here.
+   <function>Memcached::appendByKey</function> is functionally equivalent to
+   <methodname>Memcached::append</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 +31,7 @@
      <term><parameter>server_key</parameter></term>
      <listitem>
       <para>
-       Description...
+       The key identifying the server where the item is.
       </para>
      </listitem>
     </varlistentry>
@@ -37,7 +39,7 @@
      <term><parameter>key</parameter></term>
      <listitem>
       <para>
-       Description...
+       The key of the item to append the data to.
       </para>
      </listitem>
     </varlistentry>
@@ -45,15 +47,7 @@
      <term><parameter>value</parameter></term>
      <listitem>
       <para>
-       Description...
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term><parameter>expiration</parameter></term>
-     <listitem>
-      <para>
-       Description...
+       The string to append.
       </para>
      </listitem>
     </varlistentry>
@@ -64,29 +58,9 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Description...
-  </para>
- </refsect1>
-
- <refsect1 role="examples">
-  &reftitle.examples;
-  <para>
-   <example>
-    <title><function>Memcached::appendByKey</function> example</title>
-    <programlisting role="php">
-<![CDATA[
-<?php
-/* ... */
-?>
-]]>
-    </programlisting>
-    &example.outputs.similar;
-    <screen>
-<![CDATA[
-...
-]]>
-    </screen>
-   </example>
+   &return.success;
+   The <methodname>Memcached::getResultCode</methodname> will return
+   <constant>Memcached::RES_NOTSTORED</constant> if the key does not exist.
   </para>
  </refsect1>
 
@@ -94,7 +68,8 @@
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><methodname>Classname::Method</methodname></member>
+    <member><methodname>Memcached::append</methodname></member>
+    <member><methodname>Memcached::prepend</methodname></member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/memcached/memcached/prepend.xml b/reference/memcached/memcached/prepend.xml
index 076c2c2c1e..a35bb463af 100644
--- a/reference/memcached/memcached/prepend.xml
+++ b/reference/memcached/memcached/prepend.xml
@@ -1,23 +1,33 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 
 <refentry xml:id="memcached.prepend" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::prepend</refname>
-  <refpurpose>The prepend purpose</refpurpose>
+  <refpurpose>Prepend data to an existing item</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <modifier>public</modifier> <type>void</type><methodname>Memcached::prepend</methodname>
+   <modifier>public</modifier> <type>bool</type><methodname>Memcached::prepend</methodname>
    <methodparam><type>string</type><parameter>key</parameter></methodparam>
    <methodparam><type>string</type><parameter>value</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>expiration</parameter></methodparam>
   </methodsynopsis>
   <para>
-   The method description goes here.
+   <function>Memcached::prepend</function> prepends the given
+   <parameter>value</parameter> string to the value of an existing item. The
+   reason that <parameter>value</parameter> is forced to be a string is
+   that prepending mixed types is not well-defined.
   </para>
+  <note>
+   <para>
+    If the <constant>Memcached::OPT_COMPRESSION</constant> is enabled, the
+    operation will fail and a warning will be issued, because prepending
+    compressed data to a value that is potentially already compressed is not
+    possible.
+   </para>
+  </note>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -28,7 +38,7 @@
      <term><parameter>key</parameter></term>
      <listitem>
       <para>
-       Description...
+       The key of the item to prepend the data to.
       </para>
      </listitem>
     </varlistentry>
@@ -36,15 +46,7 @@
      <term><parameter>value</parameter></term>
      <listitem>
       <para>
-       Description...
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term><parameter>expiration</parameter></term>
-     <listitem>
-      <para>
-       Description...
+       The string to prepend.
       </para>
      </listitem>
     </varlistentry>
@@ -55,7 +57,9 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Description...
+   &return.success;
+   The <methodname>Memcached::getResultCode</methodname> will return
+   <constant>Memcached::RES_NOTSTORED</constant> if the key does not exist.
   </para>
  </refsect1>
 
@@ -67,14 +71,20 @@
     <programlisting role="php">
 <![CDATA[
 <?php
-/* ... */
+$m = new Memcached();
+$m->addServer('localhost', 11211);
+$m->setOption(Memcached::OPT_COMPRESSION, false);
+
+$m->set('foo', 'abc');
+$m->prepend('foo', 'def');
+var_dump($m->get('foo'));
 ?>
 ]]>
     </programlisting>
-    &example.outputs.similar;
+    &example.outputs;
     <screen>
 <![CDATA[
-...
+string(6) "defabc"
 ]]>
     </screen>
    </example>
@@ -85,7 +95,8 @@
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><methodname>Classname::Method</methodname></member>
+    <member><methodname>Memcached::prependByKey</methodname></member>
+    <member><methodname>Memcached::append</methodname></member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/memcached/memcached/prependbykey.xml b/reference/memcached/memcached/prependbykey.xml
index 057a55fdcd..39d020f619 100644
--- a/reference/memcached/memcached/prependbykey.xml
+++ b/reference/memcached/memcached/prependbykey.xml
@@ -1,23 +1,25 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 
 <refentry xml:id="memcached.prependbykey" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::prependByKey</refname>
-  <refpurpose>The prependByKey purpose</refpurpose>
+  <refpurpose>Prepend data to an existing item on a specific server</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <modifier>public</modifier> <type>void</type><methodname>Memcached::prependByKey</methodname>
+   <modifier>public</modifier> <type>bool</type><methodname>Memcached::prependByKey</methodname>
    <methodparam><type>string</type><parameter>server_key</parameter></methodparam>
    <methodparam><type>string</type><parameter>key</parameter></methodparam>
    <methodparam><type>string</type><parameter>value</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>expiration</parameter></methodparam>
   </methodsynopsis>
   <para>
-   The method description goes here.
+   <function>Memcached::prependByKey</function> is functionally equivalent to
+   <methodname>Memcached::prepend</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 +31,7 @@
      <term><parameter>server_key</parameter></term>
      <listitem>
       <para>
-       Description...
+       The key identifying the server where the item is.
       </para>
      </listitem>
     </varlistentry>
@@ -37,7 +39,7 @@
      <term><parameter>key</parameter></term>
      <listitem>
       <para>
-       Description...
+       The key of the item to prepend the data to.
       </para>
      </listitem>
     </varlistentry>
@@ -45,15 +47,7 @@
      <term><parameter>value</parameter></term>
      <listitem>
       <para>
-       Description...
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term><parameter>expiration</parameter></term>
-     <listitem>
-      <para>
-       Description...
+       The string to prepend.
       </para>
      </listitem>
     </varlistentry>
@@ -64,29 +58,9 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Description...
-  </para>
- </refsect1>
-
- <refsect1 role="examples">
-  &reftitle.examples;
-  <para>
-   <example>
-    <title><function>Memcached::prependByKey</function> example</title>
-    <programlisting role="php">
-<![CDATA[
-<?php
-/* ... */
-?>
-]]>
-    </programlisting>
-    &example.outputs.similar;
-    <screen>
-<![CDATA[
-...
-]]>
-    </screen>
-   </example>
+   &return.success;
+   The <methodname>Memcached::getResultCode</methodname> will return
+   <constant>Memcached::RES_NOTSTORED</constant> if the key does not exist.
   </para>
  </refsect1>
 
@@ -94,7 +68,8 @@
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><methodname>Classname::Method</methodname></member>
+    <member><methodname>Memcached::prepend</methodname></member>
+    <member><methodname>Memcached::append</methodname></member>
    </simplelist>
   </para>
  </refsect1>