From 4de5ce1452e6de014ca2e00366c8954b2adc8faa Mon Sep 17 00:00:00 2001
From: Andrei Zmievski <andrei@php.net>
Date: Tue, 3 Feb 2009 21:39:35 +0000
Subject: [PATCH] memcached docs progress.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@275122 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/memcached/book.xml                  |  3 +-
 reference/memcached/expiration.xml            | 43 ++++++++++++++++
 reference/memcached/memcached/add.xml         |  5 +-
 reference/memcached/memcached/addbykey.xml    |  5 +-
 reference/memcached/memcached/delete.xml      | 45 ++++++++++-------
 reference/memcached/memcached/deletebykey.xml | 49 ++++++-------------
 reference/memcached/memcached/replace.xml     |  5 +-
 .../memcached/memcached/replacebykey.xml      |  5 +-
 reference/memcached/memcached/set.xml         | 19 ++++---
 reference/memcached/memcached/setbykey.xml    |  5 +-
 reference/memcached/memcached/setmulti.xml    |  5 +-
 .../memcached/memcached/setmultibykey.xml     |  5 +-
 12 files changed, 119 insertions(+), 75 deletions(-)
 create mode 100644 reference/memcached/expiration.xml

diff --git a/reference/memcached/book.xml b/reference/memcached/book.xml
index 773ba9ca40..05e219330b 100644
--- a/reference/memcached/book.xml
+++ b/reference/memcached/book.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 
 <book xml:id="book.memcached" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Memcached</title>
@@ -32,6 +32,7 @@
  &reference.memcached.setup;
  &reference.memcached.constants;
  &reference.memcached.examples;
+ &reference.memcached.expiration;
  &reference.memcached.memcached;
 
 </book>
diff --git a/reference/memcached/expiration.xml b/reference/memcached/expiration.xml
new file mode 100644
index 0000000000..f487e536f4
--- /dev/null
+++ b/reference/memcached/expiration.xml
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 1.1 $ -->
+
+<chapter xml:id="memcached.expiration" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <title>Expiration Times</title>
+ <para>
+  Some storage commands involve sending an expiration value (relative to an
+  item or to an operation requested by the client) to the server. In all such
+  cases, the actual value sent may either be Unix time (number of seconds
+  since January 1, 1970, as an integer), or a number of seconds starting from
+  current time. In the latter case, this number of seconds may not exceed
+  60*60*24*30 (number of seconds in 30 days); if the expiration value is
+  larger than that, the server will consider it to be real Unix time value
+  rather than an offset from current time.
+ </para>
+ <para>
+  If the expiration value is <literal>0</literal> (the default), the item
+  never expires (although it may be deleted from the server to make place for
+  other items). 
+ </para>
+</chapter>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"../../../manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
+
diff --git a/reference/memcached/memcached/add.xml b/reference/memcached/memcached/add.xml
index d365ccfb29..a23a2e372e 100644
--- a/reference/memcached/memcached/add.xml
+++ b/reference/memcached/memcached/add.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 
 <refentry xml:id="memcached.add" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -46,7 +46,8 @@
      <term><parameter>expiration</parameter></term>
      <listitem>
       <para>
-       The expiration time of the value, as a Unix timestamp.
+       The expiration time, defaults to 0. See <link
+        linkend="memcached.expiration">Expiration Times</link> for more info.
       </para>
      </listitem>
     </varlistentry>
diff --git a/reference/memcached/memcached/addbykey.xml b/reference/memcached/memcached/addbykey.xml
index ed53b766f5..e0c6c65e91 100644
--- a/reference/memcached/memcached/addbykey.xml
+++ b/reference/memcached/memcached/addbykey.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 
 <refentry xml:id="memcached.addbykey" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -57,7 +57,8 @@
      <term><parameter>expiration</parameter></term>
      <listitem>
       <para>
-       The expiration time of the value, as a Unix timestamp.
+       The expiration time, defaults to 0. See <link
+        linkend="memcached.expiration">Expiration Times</link> for more info.
       </para>
      </listitem>
     </varlistentry>
diff --git a/reference/memcached/memcached/delete.xml b/reference/memcached/memcached/delete.xml
index e582df44a6..2201566bfb 100644
--- a/reference/memcached/memcached/delete.xml
+++ b/reference/memcached/memcached/delete.xml
@@ -1,21 +1,33 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 
 <refentry xml:id="memcached.delete" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::delete</refname>
-  <refpurpose>The delete purpose</refpurpose>
+  <refpurpose>Delete an item</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <modifier>public</modifier> <type>void</type><methodname>Memcached::delete</methodname>
+   <modifier>public</modifier> <type>bool</type><methodname>Memcached::delete</methodname>
    <methodparam><type>string</type><parameter>key</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>expiration</parameter></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>time</parameter></methodparam>
   </methodsynopsis>
   <para>
-   The method description goes here.
+   <function>Memcached::delete</function> deletes the
+   <parameter>key</parameter> from the server. The <parameter>time</parameter>
+   parameter is the amount of time in seconds (or Unix time until which) the
+   client wishes the server to refuse <literal>add</literal> and
+   <literal>replace</literal> commands for this key. For this amount of time,
+   the item is put into a delete queue, which means that it won't possible to
+   retrieve it by the <literal>get</literal> command, but
+   <literal>add</literal> and <literal>replace</literal> command with this key
+   will also fail (the <literal>set</literal> command will succeed, however).
+   After the time passes, the item is finally deleted from server memory. The
+   parameter <parameter>time</parameter> defaults to 0 (which means that the
+   item will be deleted immediately and further storage commands with this key
+   will succeed).
   </para>
  </refsect1>
 
@@ -27,15 +39,16 @@
      <term><parameter>key</parameter></term>
      <listitem>
       <para>
-       Description...
+       The key to be deleted.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><parameter>expiration</parameter></term>
+     <term><parameter>time</parameter></term>
      <listitem>
       <para>
-       Description...
+       The amount of time the server will wait to delete the item. Defaults to
+       <literal>0</literal>.
       </para>
      </listitem>
     </varlistentry>
@@ -46,7 +59,8 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Description...
+   &return.success;
+   Use <methodname>Memcached::getResultCode</methodname> if necessary.
   </para>
  </refsect1>
 
@@ -58,16 +72,13 @@
     <programlisting role="php">
 <![CDATA[
 <?php
-/* ... */
+$m = new Memcached();
+$m->addServer('localhost', 11211);
+
+$m->delete('key1');
 ?>
 ]]>
     </programlisting>
-    &example.outputs.similar;
-    <screen>
-<![CDATA[
-...
-]]>
-    </screen>
    </example>
   </para>
  </refsect1>
@@ -76,7 +87,7 @@
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><methodname>Classname::Method</methodname></member>
+    <member><methodname>Memcached::deleteByKey</methodname></member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/memcached/memcached/deletebykey.xml b/reference/memcached/memcached/deletebykey.xml
index ad1375ca8b..a96c9b01e4 100644
--- a/reference/memcached/memcached/deletebykey.xml
+++ b/reference/memcached/memcached/deletebykey.xml
@@ -1,22 +1,25 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 
 <refentry xml:id="memcached.deletebykey" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::deleteByKey</refname>
-  <refpurpose>The deleteByKey purpose</refpurpose>
+  <refpurpose>Delete an item from a specific server</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <modifier>public</modifier> <type>void</type><methodname>Memcached::deleteByKey</methodname>
+   <modifier>public</modifier> <type>bool</type><methodname>Memcached::deleteByKey</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>expiration</parameter></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>time</parameter></methodparam>
   </methodsynopsis>
   <para>
-   The method description goes here.
+   <function>Memcached::deleteByKey</function> is functionally equivalent to
+   <methodname>Memcached::delete</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>
 
@@ -28,7 +31,7 @@
      <term><parameter>server_key</parameter></term>
      <listitem>
       <para>
-       Description...
+       The key identifying the server to delete the item from.
       </para>
      </listitem>
     </varlistentry>
@@ -36,15 +39,16 @@
      <term><parameter>key</parameter></term>
      <listitem>
       <para>
-       Description...
+       The key to be deleted.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><parameter>expiration</parameter></term>
+     <term><parameter>time</parameter></term>
      <listitem>
       <para>
-       Description...
+       The amount of time the server will wait to delete the item. Defaults to
+       <literal>0</literal>.
       </para>
      </listitem>
     </varlistentry>
@@ -55,29 +59,8 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Description...
-  </para>
- </refsect1>
-
- <refsect1 role="examples">
-  &reftitle.examples;
-  <para>
-   <example>
-    <title><function>Memcached::deleteByKey</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>
 
@@ -85,7 +68,7 @@
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><methodname>Classname::Method</methodname></member>
+    <member><methodname>Memcached::delete</methodname></member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/memcached/memcached/replace.xml b/reference/memcached/memcached/replace.xml
index c0df267c9e..d0f6e772bf 100644
--- a/reference/memcached/memcached/replace.xml
+++ b/reference/memcached/memcached/replace.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 
 <refentry xml:id="memcached.replace" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -46,7 +46,8 @@
      <term><parameter>expiration</parameter></term>
      <listitem>
       <para>
-       The expiration time of the value, as a Unix timestamp.
+       The expiration time, defaults to 0. See <link
+        linkend="memcached.expiration">Expiration Times</link> for more info.
       </para>
      </listitem>
     </varlistentry>
diff --git a/reference/memcached/memcached/replacebykey.xml b/reference/memcached/memcached/replacebykey.xml
index 8c81fb02ff..550a325290 100644
--- a/reference/memcached/memcached/replacebykey.xml
+++ b/reference/memcached/memcached/replacebykey.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 
 <refentry xml:id="memcached.replacebykey" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -57,7 +57,8 @@
      <term><parameter>expiration</parameter></term>
      <listitem>
       <para>
-       The expiration time of the value, as a Unix timestamp.
+       The expiration time, defaults to 0. See <link
+        linkend="memcached.expiration">Expiration Times</link> for more info.
       </para>
      </listitem>
     </varlistentry>
diff --git a/reference/memcached/memcached/set.xml b/reference/memcached/memcached/set.xml
index 264eaba0ff..ddcc9daa5d 100644
--- a/reference/memcached/memcached/set.xml
+++ b/reference/memcached/memcached/set.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 
 <refentry xml:id="memcached.set" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -18,16 +18,14 @@
   <para>
    <function>Memcached::set</function> stores the <parameter>value</parameter>
    on a memcache server under the specified <parameter>key</parameter>. The
-   <parameter>expiration</parameter> parameter is a Unix timestamp that can be
-   used to control when the value is considered expired. It can be set to
-   <literal>0</literal> which means that the value will persist until the
-   server deletes it to make space for new items.
+   <parameter>expiration</parameter> parameter can be used to control when the
+   value is considered expired.
   </para>
   <para>
-   The value can be any valid PHP type except for resources, because
-   those cannot be represented in a serialized form. If the
-   <constant>Memcached::OPT_COMPRESSION</constant> option is turned on, the serialized
-   value will also be compressed before storage.
+   The value can be any valid PHP type except for resources, because those
+   cannot be represented in a serialized form. If the
+   <constant>Memcached::OPT_COMPRESSION</constant> option is turned on, the
+   serialized value will also be compressed before storage.
   </para>
  </refsect1>
 
@@ -55,7 +53,8 @@
      <term><parameter>expiration</parameter></term>
      <listitem>
       <para>
-       The expiration time of the value, as a Unix timestamp.
+       The expiration time, defaults to 0. See <link
+        linkend="memcached.expiration">Expiration Times</link> for more info.
       </para>
      </listitem>
     </varlistentry>
diff --git a/reference/memcached/memcached/setbykey.xml b/reference/memcached/memcached/setbykey.xml
index f44b5ee5a6..9f2122c6d7 100644
--- a/reference/memcached/memcached/setbykey.xml
+++ b/reference/memcached/memcached/setbykey.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 
 <refentry xml:id="memcached.setbykey" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -57,7 +57,8 @@
      <term><parameter>expiration</parameter></term>
      <listitem>
       <para>
-       The expiration time of the value, as a Unix timestamp.
+       The expiration time, defaults to 0. See <link
+        linkend="memcached.expiration">Expiration Times</link> for more info.
       </para>
      </listitem>
     </varlistentry>
diff --git a/reference/memcached/memcached/setmulti.xml b/reference/memcached/memcached/setmulti.xml
index ef69958c6d..3a5e54d174 100644
--- a/reference/memcached/memcached/setmulti.xml
+++ b/reference/memcached/memcached/setmulti.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 
 <refentry xml:id="memcached.setmulti" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -39,7 +39,8 @@
      <term><parameter>expiration</parameter></term>
      <listitem>
       <para>
-       The expiration time of the entries, as a Unix timestamp.
+       The expiration time, defaults to 0. See <link
+        linkend="memcached.expiration">Expiration Times</link> for more info.
       </para>
      </listitem>
     </varlistentry>
diff --git a/reference/memcached/memcached/setmultibykey.xml b/reference/memcached/memcached/setmultibykey.xml
index 916a31e211..d85e80c53f 100644
--- a/reference/memcached/memcached/setmultibykey.xml
+++ b/reference/memcached/memcached/setmultibykey.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 
 <refentry xml:id="memcached.setmultibykey" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -48,7 +48,8 @@
      <term><parameter>expiration</parameter></term>
      <listitem>
       <para>
-       The expiration time of the entries, as a Unix timestamp.
+       The expiration time, defaults to 0. See <link
+        linkend="memcached.expiration">Expiration Times</link> for more info.
       </para>
      </listitem>
     </varlistentry>