From f4d16c3936371a93765f39bfa4e7b4c6ad42774e Mon Sep 17 00:00:00 2001
From: Andrei Zmievski <andrei@php.net>
Date: Fri, 6 Feb 2009 22:18:23 +0000
Subject: [PATCH] docs progress

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@275308 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/memcached/book.xml                  |  4 +-
 reference/memcached/callbacks.xml             | 95 ++++++++++++++++++-
 reference/memcached/memcached/getmulti.xml    |  4 +-
 .../memcached/memcached/getresultcode.xml     | 35 +++----
 4 files changed, 110 insertions(+), 28 deletions(-)

diff --git a/reference/memcached/book.xml b/reference/memcached/book.xml
index 0a4f3e581e..be8497535c 100644
--- a/reference/memcached/book.xml
+++ b/reference/memcached/book.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 
 <book xml:id="book.memcached" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Memcached</title>
@@ -31,9 +31,9 @@
 
  &reference.memcached.setup;
  &reference.memcached.constants;
- &reference.memcached.callbacks;
  &reference.memcached.examples;
  &reference.memcached.expiration;
+ &reference.memcached.callbacks;
  &reference.memcached.memcached;
 
 </book>
diff --git a/reference/memcached/callbacks.xml b/reference/memcached/callbacks.xml
index b4cf848f9b..bb573c66eb 100644
--- a/reference/memcached/callbacks.xml
+++ b/reference/memcached/callbacks.xml
@@ -1,12 +1,101 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 
 <chapter xml:id="memcached.callbacks" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Callbacks</title>
 
- <section xml:id="memcached.callbacks.placeholder">
-  <para>Placeholder</para>
+ <section xml:id="memcached.callbacks.result">
+  <title>Result callbacks</title>
+  <para>
+   Result callbacks are invoked by
+   <methodname>Memcached::getDelayed</methodname> or
+   <methodname>Memcached::getDelayedBykey</methodname> methods for each item in
+   the result set. The callback is passed the Memcached object and the array
+   with the item information. The callback does not have to return anything.
+  </para>
+  <example>
+   <title>Result callback example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$m = new Memcached();
+$m->addServer('localhost', 11211);
+$items = array(
+    'key1' => 'value1',
+    'key2' => 'value2',
+    'key3' => 'value3'
+);
+$m->setMulti($items);
+$m->getDelayed(array('key1', 'key3'), true, 'result_cb');
+
+function result_cb($memc, $item)
+{
+    var_dump($item);
+}
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+array(3) {
+  ["key"]=>
+  string(4) "key1"
+  ["value"]=>
+  string(6) "value1"
+  ["cas"]=>
+  float(49)
+}
+array(3) {
+  ["key"]=>
+  string(4) "key3"
+  ["value"]=>
+  string(6) "value3"
+  ["cas"]=>
+  float(50)
+}
+]]>
+   </screen>
+  </example>
  </section>
+
+ <section xml:id="memcached.callbacks.read-through">
+  <title>Read-through cache callbacks</title>
+  <para>
+   Read-through cache callbacks are invoked when an item cannot be retrieved
+   from the server. The callback is passed the Memcached object, the requested
+   key, and the by-reference value variable. The callback is responsible for
+   setting the value and returning true or false. If the callback returns true,
+   Memcached will store the populated value on the server and return it to the
+   original calling function. Only <methodname>Memcached::get</methodname> and
+   <methodname>Memcached::getByKey</methodname> support these callbacks,
+   because the memcache protocol does not provide information on which keys
+   were not found in the multi-key request.
+  </para>
+  <example>
+   <title>Read-through callback example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$m = new Memcached();
+$m->addServer('localhost', 11211);
+
+$profile_info = $m->get('user:'.$user_id, 'user_info_cb');
+
+function user_info_cb($memc, $key, &$value)
+{
+    $user_id = substr($key, 5);
+    /* lookup profile info in the DB */
+    ...
+    $value = $profile_info;
+    return true;
+}
+?>
+]]>
+   </programlisting>
+  </example>
+ </section>
+
 </chapter>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/memcached/memcached/getmulti.xml b/reference/memcached/memcached/getmulti.xml
index 3fb102cb24..e90c6b1d39 100644
--- a/reference/memcached/memcached/getmulti.xml
+++ b/reference/memcached/memcached/getmulti.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 
 <refentry xml:id="memcached.getmulti" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -26,7 +26,7 @@
      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
+     does not provide information on which keys were not found in the multi-key
      request.
     </para>
    </note>
diff --git a/reference/memcached/memcached/getresultcode.xml b/reference/memcached/memcached/getresultcode.xml
index 651ab2cda8..528fda1f56 100644
--- a/reference/memcached/memcached/getresultcode.xml
+++ b/reference/memcached/memcached/getresultcode.xml
@@ -1,20 +1,22 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 
 <refentry xml:id="memcached.getresultcode" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Memcached::getResultCode</refname>
-  <refpurpose>The getResultCode purpose</refpurpose>
+  <refpurpose>Return the result code of the last operation</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <modifier>public</modifier> <type>void</type><methodname>Memcached::getResultCode</methodname>
+   <modifier>public</modifier> <type>int</type><methodname>Memcached::getResultCode</methodname>
    <void />
   </methodsynopsis>
   <para>
-   The method description goes here.
+   <function>Memcached::getResultCode</function> returns one of the
+   <constant>Memcached::RES_*</constant> constants that is the result of the
+   last executed Memcached method.
   </para>
  </refsect1>
 
@@ -26,7 +28,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Description...
+   Result code of the last Memcached operation.
   </para>
  </refsect1>
 
@@ -38,29 +40,20 @@
     <programlisting role="php">
 <![CDATA[
 <?php
-/* ... */
+$m = new Memcached();
+$m->addServer('localhost', 11211);
+
+$m->add('foo', 'bar');
+if ($m->getResultCode() == Memcached::RES_NOTSTORED) {
+    ...
+}
 ?>
 ]]>
     </programlisting>
-    &example.outputs.similar;
-    <screen>
-<![CDATA[
-...
-]]>
-    </screen>
    </example>
   </para>
  </refsect1>
 
- <refsect1 role="seealso">
-  &reftitle.seealso;
-  <para>
-   <simplelist>
-    <member><methodname>Classname::Method</methodname></member>
-   </simplelist>
-  </para>
- </refsect1>
-
 </refentry>
 
 <!-- Keep this comment at the end of the file