[prev in list] [next in list] [prev in thread] [next in thread]
List: php-doc-cvs
Subject: [DOC-CVS] [doc-en] master: Improve documentation of the Memcached delete methods
From: Tim Starling via GitHub <noreply () php ! net>
Date: 2022-11-15 23:40:03
Message-ID: zmJxLASn9F2TwW3qF0LUrGkaqlJNIW3a08ISmMVWQ () main ! php ! net
[Download RAW message or body]
Author: Tim Starling (tstarling)
Committer: GitHub (web-flow)
Pusher: tstarling
Date: 2022-11-16T10:29:21+11:00
Commit: https://github.com/php/doc-en/commit/af154fb2099c5c029de9d1dd1174cf11f135bfa0
Raw diff: https://github.com/php/doc-en/commit/af154fb2099c5c029de9d1dd1174cf11f135bfa0.diff
Improve documentation of the Memcached delete methods
* Note that it's always an error to specify a non-zero time parameter,
and delete the long-winded explanations of what it is meant to do.
* Expand the description of the return value from deleteMulti().
* Replace the incorrect description of the return value of
deleteMultiByKey(). Use the one from deleteMulti() instead.
* Explain what getResultCode() will return after deleteMulti().
Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>
Changed paths:
M language-snippets.ent
M reference/memcached/memcached/delete.xml
M reference/memcached/memcached/deletebykey.xml
M reference/memcached/memcached/deletemulti.xml
M reference/memcached/memcached/deletemultibykey.xml
Diff:
diff --git a/language-snippets.ent b/language-snippets.ent
index c06ec0b8116..1253b2b546b 100644
--- a/language-snippets.ent
+++ b/language-snippets.ent
@@ -1256,6 +1256,14 @@ encoding value will be used.</para>'>
<!-- memcached notes -->
+<!ENTITY memcached.note.delete-time '<note \
xmlns="http://docbook.org/ns/docbook"><simpara> + As of memcached 1.3.0 \
(released 2009) this feature is no longer + supported. Passing a non-zero \
<parameter>time</parameter> will cause + the deletion to fail. \
<methodname>Memcached::getResultCode</methodname> + will return \
<constant>MEMCACHED_INVALID_ARGUMENTS</constant>. + </simpara></note>
+'>
+
<!ENTITY memcached.parameter.expiration 'The expiration time, defaults to 0. See \
<link linkend="memcached.expiration" \
xmlns="http://docbook.org/ns/docbook">Expiration Times</link> for more info.'>
@@ -1269,6 +1277,19 @@ encoding value will be used.</para>'>
<!ENTITY memcached.result.getresultcode 'Use <methodname \
xmlns="http://docbook.org/ns/docbook">Memcached::getResultCode</methodname> if \
necessary.'>
+<!ENTITY memcached.result.delete-multi '<para xmlns="http://docbook.org/ns/docbook">
+ Returns an array indexed by <parameter>keys</parameter>. Each element
+ is &true; if the corresponding key was deleted, or one of the
+ <constant>Memcached::RES_*</constant> constants if the corresponding deletion
+ failed.
+ </para>
+ <para xmlns="http://docbook.org/ns/docbook">
+ The <methodname>Memcached::getResultCode</methodname> will return
+ the result code for the last executed delete operation, that is, the delete
+ operation for the last element of <parameter>keys</parameter>.
+ </para>
+'>
+
<!-- password notes -->
<!ENTITY password.parameter.algo 'A <link xmlns="http://docbook.org/ns/docbook" \
linkend="password.constants">password algorithm constant</link> denoting the \
algorithm to use when hashing the password.'>
diff --git a/reference/memcached/memcached/delete.xml \
b/reference/memcached/memcached/delete.xml index e34db32593b..3b7d0aab262 100644
--- a/reference/memcached/memcached/delete.xml
+++ b/reference/memcached/memcached/delete.xml
@@ -15,19 +15,7 @@
<methodparam choice="opt"><type>int</type><parameter>time</parameter><initializer>0</initializer></methodparam>
</methodsynopsis>
<para>
- <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).
+ Delete the <parameter>key</parameter> from the server.
</para>
</refsect1>
@@ -49,6 +37,7 @@
<para>
The amount of time the server will wait to delete the item.
</para>
+ &memcached.note.delete-time;
</listitem>
</varlistentry>
</variablelist>
diff --git a/reference/memcached/memcached/deletebykey.xml \
b/reference/memcached/memcached/deletebykey.xml index d7b1a76b236..52da08e7433 100644
--- a/reference/memcached/memcached/deletebykey.xml
+++ b/reference/memcached/memcached/deletebykey.xml
@@ -49,6 +49,7 @@
<para>
The amount of time the server will wait to delete the item.
</para>
+ &memcached.note.delete-time;
</listitem>
</varlistentry>
</variablelist>
diff --git a/reference/memcached/memcached/deletemulti.xml \
b/reference/memcached/memcached/deletemulti.xml index 3cb06a7c3fd..6d286b6f453 100644
--- a/reference/memcached/memcached/deletemulti.xml
+++ b/reference/memcached/memcached/deletemulti.xml
@@ -15,21 +15,8 @@
<methodparam choice="opt"><type>int</type><parameter>time</parameter><initializer>0</initializer></methodparam>
</methodsynopsis>
<para>
- <function>Memcached::deleteMulti</function> deletes the array of
- <parameter>keys</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 these keys. For this amount of time,
- the item is put into a delete queue, which means that it won't be possible to
- retrieve it by the <literal>get</literal> command, but
- <literal>add</literal> and <literal>replace</literal> command with these keys
- 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 these keys
- will succeed).
+ Delete the array of <parameter>keys</parameter> from the server.
</para>
-
</refsect1>
<refsect1 role="parameters">
@@ -50,6 +37,7 @@
<para>
The amount of time the server will wait to delete the items.
</para>
+ &memcached.note.delete-time;
</listitem>
</varlistentry>
</variablelist>
@@ -58,11 +46,7 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
- Returns array indexed by <parameter>keys</parameter> and where values are \
indicating whether operation succeeded or not.
- The <methodname>Memcached::getResultCode</methodname> will return
- <constant>Memcached::RES_NOTFOUND</constant> if the key does not exist.
- </para>
+ &memcached.result.delete-multi;
</refsect1>
<refsect1 role="seealso">
diff --git a/reference/memcached/memcached/deletemultibykey.xml \
b/reference/memcached/memcached/deletemultibykey.xml index 7f39f415eb0..924e7667f58 \
100644
--- a/reference/memcached/memcached/deletemultibykey.xml
+++ b/reference/memcached/memcached/deletemultibykey.xml
@@ -50,6 +50,7 @@
<para>
The amount of time the server will wait to delete the items.
</para>
+ &memcached.note.delete-time;
</listitem>
</varlistentry>
</variablelist>
@@ -58,11 +59,7 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
- &return.success;
- The <methodname>Memcached::getResultCode</methodname> will return
- <constant>Memcached::RES_NOTFOUND</constant> if the key does not exist.
- </para>
+ &memcached.result.delete-multi;
</refsect1>
<refsect1 role="seealso">
--
PHP Documentation Commits Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic