From df836162e88e6ac51d47c26908df64fb122414ce Mon Sep 17 00:00:00 2001
From: Laurenz Albe <laurenz.albe@cybertec.at>
Date: Thu, 1 Dec 2022 22:16:28 +0100
Subject: [PATCH] Improve sequence manipulation function doc

Point to the example section of CREATE SEQUENCE for examples.
Add "--" before comments interleaved with code.
Some slight rewording.

Author: Kirk Wolak
---
 doc/src/sgml/func.sgml                | 20 ++++++++++++--------
 doc/src/sgml/ref/create_sequence.sgml |  2 +-
 2 files changed, 13 insertions(+), 9 deletions(-)

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 6e0425cb3d..2391deabea 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -17623,7 +17623,7 @@ $.* ? (@ like_regex "^\\d+$")
         values beginning with 1.  Other behaviors can be obtained by using
         appropriate parameters in the <xref linkend="sql-createsequence"/>
         command.
-      </para>
+       </para>
        <para>
         This function requires <literal>USAGE</literal>
         or <literal>UPDATE</literal> privilege on the sequence.
@@ -17657,11 +17657,11 @@ $.* ? (@ like_regex "^\\d+$")
         Furthermore, the value reported by <function>currval</function> is not
         changed in this case.  For example,
 <programlisting>
-SELECT setval('myseq', 42);           <lineannotation>Next <function>nextval</function> will return 43</lineannotation>
-SELECT setval('myseq', 42, true);     <lineannotation>Same as above</lineannotation>
-SELECT setval('myseq', 42, false);    <lineannotation>Next <function>nextval</function> will return 42</lineannotation>
+SELECT setval('myseq', 42);           <lineannotation>-- The next <function>nextval</function>('myseq') will return 43</lineannotation>
+SELECT setval('myseq', 42, true);     <lineannotation>-- Same as above</lineannotation>
+SELECT setval('myseq', 42, false);    <lineannotation>-- The next <function>nextval</function>('myseq') will return 42</lineannotation>
 </programlisting>
-        The result returned by <function>setval</function> is just the value of its
+        The result returned by <function>setval</function> is the value of its
         second argument.
        </para>
        <para>
@@ -17707,9 +17707,8 @@ SELECT setval('myseq', 42, false);    <lineannotation>Next <function>nextval</fu
         identical to <function>currval</function>, except that instead
         of taking the sequence name as an argument it refers to whichever
         sequence <function>nextval</function> was most recently applied to
-        in the current session. It is an error to call
-        <function>lastval</function> if <function>nextval</function>
-        has not yet been called in the current session.
+        in the current session. (An error is reported if <function>nextval</function> has
+        never been called in this session.)
        </para>
        <para>
         This function requires <literal>USAGE</literal>
@@ -17720,6 +17719,11 @@ SELECT setval('myseq', 42, false);    <lineannotation>Next <function>nextval</fu
     </tgroup>
    </table>
 
+  <para>
+   You can see sequence manipulation functions being used in the
+   <xref linkend="sql-createsequence-examples"/>.
+  </para>
+
   <caution>
    <para>
     To avoid blocking concurrent transactions that obtain numbers from
diff --git a/doc/src/sgml/ref/create_sequence.sgml b/doc/src/sgml/ref/create_sequence.sgml
index 34e9084b5c..d417405930 100644
--- a/doc/src/sgml/ref/create_sequence.sgml
+++ b/doc/src/sgml/ref/create_sequence.sgml
@@ -329,7 +329,7 @@ SELECT * FROM <replaceable>name</replaceable>;
   </para>
  </refsect1>
 
- <refsect1>
+ <refsect1 id="sql-createsequence-examples" xreflabel="Examples for CREATE SEQUENCE">
   <title>Examples</title>
 
   <para>
-- 
2.38.1