From 507aa16125c50809dfc926e7ee72938053c01a39 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Thu, 25 Sep 2025 11:23:27 -0400
Subject: [PATCH] Doc: clean up documentation for new UUID functions.

Fix assorted failures to conform to our normal style for function
documentation, such as lack of parentheses and incorrect markup.

Author: Marcos Pegoraro <marcos@f10.com.br>
Co-authored-by: Tom Lane <tgl@sss.pgh.pa.us>
Discussion: https://postgr.es/m/CAB-JLwbocrFjKfGHoKY43pHTf49Ca2O0j3WVebC8z-eQBMPJyw@mail.gmail.com
Backpatch-through: 18
---
 doc/src/sgml/func/func-uuid.sgml | 75 ++++++++++++++------------------
 1 file changed, 33 insertions(+), 42 deletions(-)

diff --git a/doc/src/sgml/func/func-uuid.sgml b/doc/src/sgml/func/func-uuid.sgml
index 65c5ddec6b7..2638e2bf855 100644
--- a/doc/src/sgml/func/func-uuid.sgml
+++ b/doc/src/sgml/func/func-uuid.sgml
@@ -36,8 +36,7 @@
    <tgroup cols="1">
     <thead>
      <row>
-      <entry role="func_table_entry">
-       <para role="func_signature">
+      <entry role="func_table_entry"><para role="func_signature">
         Function
        </para>
        <para>
@@ -45,24 +44,22 @@
         </para>
        <para>
         Example(s)
-       </para>
-       </entry>
+       </para></entry>
      </row>
     </thead>
 
     <tbody>
      <row>
-      <entry role="func_table_entry">
-       <para role="func_signature">
-        <type>gen_random_uuid</type>
+      <entry role="func_table_entry"><para role="func_signature">
+        <function>gen_random_uuid</function> ( )
         <returnvalue>uuid</returnvalue>
        </para>
        <para role="func_signature">
-        <type>uuidv4</type>
+        <function>uuidv4</function> ( )
         <returnvalue>uuid</returnvalue>
        </para>
        <para>
-         Generate a version 4 (random) UUID.
+        Generates a version 4 (random) UUID
        </para>
        <para>
         <literal>gen_random_uuid()</literal>
@@ -71,26 +68,25 @@
        <para>
         <literal>uuidv4()</literal>
         <returnvalue>b42410ee-132f-42ee-9e4f-09a6485c95b8</returnvalue>
-       </para>
-      </entry>
+       </para></entry>
      </row>
      <row>
-      <entry role="func_table_entry">
-       <para role="func_signature">
-        <type>uuidv7</type>
+      <entry role="func_table_entry"><para role="func_signature">
+        <function>uuidv7</function>
         ( <optional> <parameter>shift</parameter> <type>interval</type> </optional> )
         <returnvalue>uuid</returnvalue>
        </para>
        <para>
-        Generate a version 7 (time-ordered) UUID. The timestamp is computed using UNIX timestamp
-        with millisecond precision + sub-millisecond timestamp + random. The optional parameter
-        <parameter>shift</parameter> will shift the computed timestamp by the given <type>interval</type>.
+        Generates a version 7 (time-ordered) UUID. The timestamp is
+        computed using UNIX timestamp with millisecond precision +
+        sub-millisecond timestamp + random. The optional
+        parameter <parameter>shift</parameter> will shift the computed
+        timestamp by the given <type>interval</type>.
        </para>
        <para>
         <literal>uuidv7()</literal>
         <returnvalue>019535d9-3df7-79fb-b466-fa907fa17f9e</returnvalue>
-       </para>
-      </entry>
+       </para></entry>
      </row>
     </tbody>
    </tgroup>
@@ -113,8 +109,7 @@
    <tgroup cols="1">
     <thead>
      <row>
-      <entry role="func_table_entry">
-       <para role="func_signature">
+      <entry role="func_table_entry"><para role="func_signature">
         Function
        </para>
        <para>
@@ -122,44 +117,41 @@
        </para>
        <para>
         Example(s)
-       </para>
-      </entry>
+       </para></entry>
      </row>
     </thead>
 
     <tbody>
      <row>
-      <entry role="func_table_entry">
-       <para role="func_signature">
-        <type>uuid_extract_timestamp</type>
+      <entry role="func_table_entry"><para role="func_signature">
+        <function>uuid_extract_timestamp</function>
         ( <type>uuid</type> )
         <returnvalue>timestamp with time zone</returnvalue>
        </para>
        <para>
-        Extracts a <type>timestamp with time zone</type> from UUID
-        version 1 and 7.  For other versions, this function returns null.  Note that
-        the extracted timestamp is not necessarily exactly equal to the time the
-        UUID was generated; this depends on the implementation that generated the
-        UUID.
+        Extracts a <type>timestamp with time zone</type> from a UUID of
+        version 1 or 7.  For other versions, this function returns null.
+        Note that the extracted timestamp is not necessarily exactly equal
+        to the time the UUID was generated; this depends on the
+        implementation that generated the UUID.
        </para>
        <para>
         <literal>uuid_extract_timestamp('019535d9-3df7-79fb-b466-&zwsp;fa907fa17f9e'::uuid)</literal>
          <returnvalue>2025-02-23 21:46:24.503-05</returnvalue>
-       </para>
-      </entry>
+       </para></entry>
      </row>
      <row>
-      <entry role="func_table_entry">
-       <para role="func_signature">
-        <type>uuid_extract_version</type>
+      <entry role="func_table_entry"><para role="func_signature">
+        <function>uuid_extract_version</function>
         ( <type>uuid</type> )
         <returnvalue>smallint</returnvalue>
        </para>
        <para>
-        Extracts the version from a UUID of the variant described by
-        <ulink url="https://datatracker.ietf.org/doc/html/rfc9562">RFC 9562</ulink>.  For
-        other variants, this function returns null.  For example, for a UUID
-        generated by <function>gen_random_uuid</function>, this function will
+        Extracts the version from a UUID of one of the variants described by
+        <ulink url="https://datatracker.ietf.org/doc/html/rfc9562">RFC
+        9562</ulink>.  For other variants, this function returns null.
+        For example, for a UUID generated
+        by <function>gen_random_uuid()</function>, this function will
         return 4.
        </para>
        <para>
@@ -169,8 +161,7 @@
        <para>
         <literal>uuid_extract_version('019535d9-3df7-79fb-b466-&zwsp;fa907fa17f9e'::uuid)</literal>
         <returnvalue>7</returnvalue>
-       </para>
-      </entry>
+       </para></entry>
      </row>
     </tbody>
    </tgroup>
-- 
2.47.3