From 1071ba183a2181f109cbd5b2a597637b3b145a8c Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Sun, 17 Aug 2014 15:59:06 -0400
Subject: [PATCH] Improve DISCARD documentation.

The new DISCARD SEQUENCES option was inadequately described, and hadn't
been mentioned at all in the initial Description paragraph.  Rather than
rectifying the latter the hard way, it seemed better to rewrite the
description as a summary, instead of having it basically duplicate
statements made under Parameters.  Be more consistent about the ordering
of the options, too.
---
 doc/src/sgml/ref/discard.sgml | 44 +++++++++++++++++------------------
 1 file changed, 22 insertions(+), 22 deletions(-)

diff --git a/doc/src/sgml/ref/discard.sgml b/doc/src/sgml/ref/discard.sgml
index 5b06a638c5..e859bf7bab 100644
--- a/doc/src/sgml/ref/discard.sgml
+++ b/doc/src/sgml/ref/discard.sgml
@@ -30,16 +30,10 @@ DISCARD { ALL | PLANS | SEQUENCES | TEMPORARY | TEMP }
 
   <para>
    <command>DISCARD</> releases internal resources associated with a
-   database session. These resources are normally released at the end
-   of the session.
-  </para>
-
-  <para>
-   <command>DISCARD TEMP</> drops all temporary tables created in the
-   current session.  <command>DISCARD PLANS</> releases all internally
-   cached query plans.  <command>DISCARD ALL</> resets a session to
-   its original state, discarding temporary resources and resetting
-   session-local configuration changes.
+   database session.  This command is useful for partially or fully
+   resetting the session's state.  There are several subcommands to
+   release different types of resources; the <command>DISCARD ALL</>
+   variant subsumes all the others, and also resets additional state.
   </para>
  </refsect1>
 
@@ -48,20 +42,12 @@ DISCARD { ALL | PLANS | SEQUENCES | TEMPORARY | TEMP }
 
   <variablelist>
 
-   <varlistentry>
-    <term><literal>TEMPORARY</literal> or <literal>TEMP</literal></term>
-    <listitem>
-     <para>
-      Drops all temporary tables created in the current session.
-     </para>
-    </listitem>
-   </varlistentry>
-
    <varlistentry>
     <term><literal>PLANS</literal></term>
     <listitem>
      <para>
-      Releases all cached query plans.
+      Releases all cached query plans, forcing re-planning to occur
+      the next time the associated prepared statement is used.
      </para>
     </listitem>
    </varlistentry>
@@ -70,7 +56,21 @@ DISCARD { ALL | PLANS | SEQUENCES | TEMPORARY | TEMP }
     <term><literal>SEQUENCES</literal></term>
     <listitem>
      <para>
-      Discards all cached sequence values.
+      Discards all cached sequence-related state,
+      including <function>currval()</>/<function>lastval()</>
+      information and any preallocated sequence values that have not
+      yet been returned by <function>nextval()</>.
+      (See <xref linkend="sql-createsequence"> for a description of
+      preallocated sequence values.)
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><literal>TEMPORARY</literal> or <literal>TEMP</literal></term>
+    <listitem>
+     <para>
+      Drops all temporary tables created in the current session.
      </para>
     </listitem>
    </varlistentry>
@@ -91,8 +91,8 @@ CLOSE ALL;
 UNLISTEN *;
 SELECT pg_advisory_unlock_all();
 DISCARD PLANS;
-DISCARD TEMP;
 DISCARD SEQUENCES;
+DISCARD TEMP;
 </programlisting></para>
     </listitem>
    </varlistentry>