Skip to content

Improve documentation of the Memcached delete methods #1957

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Nov 15, 2022
Merged

Improve documentation of the Memcached delete methods #1957

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6627db9
Improve documentation of the Memcached delete methods
tstarling Nov 7, 2022
793995d
libMemcached -> libmemcached
tstarling Nov 7, 2022
e76f03b
Be more specific about "raise an error"
tstarling Nov 10, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions language-snippets.ent
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1259,6 +1259,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.'>

Expand All @@ -1272,6 +1280,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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If #1963 will be merge, this should be:

Suggested change
<constant>Memcached::RES_*</constant> constants if the corresponding deletion
<constant><replaceable>Memcached::RES_*</replaceable></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.'>
Expand Down
15 changes: 2 additions & 13 deletions reference/memcached/memcached/delete.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>

Expand All @@ -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>
Expand Down
1 change: 1 addition & 0 deletions reference/memcached/memcached/deletebykey.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
22 changes: 3 additions & 19 deletions reference/memcached/memcached/deletemulti.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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">
Expand All @@ -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>
Expand All @@ -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">
Expand Down
7 changes: 2 additions & 5 deletions reference/memcached/memcached/deletemultibykey.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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">
Expand Down