From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Thu, 25 Sep 2025 15:23:27 +0000 (-0400)
Subject: Doc: clean up documentation for new UUID functions.
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=cbfcb7b466052518e3ddcc784946aa1cfa3f3460;p=thirdparty%2Fpostgresql.git

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
---

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 8a347bec62c..d2b6b01777e 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -14419,8 +14419,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
    <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>
@@ -14428,24 +14427,22 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
         </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>
@@ -14454,26 +14451,25 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
        <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>
@@ -14496,8 +14492,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
    <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>
@@ -14505,44 +14500,41 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
        </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>
@@ -14552,8 +14544,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
        <para>
         <literal>uuid_extract_version('019535d9-3df7-79fb-b466-&zwsp;fa907fa17f9e'::uuid)</literal>
         <returnvalue>7</returnvalue>
-       </para>
-      </entry>
+       </para></entry>
      </row>
     </tbody>
    </tgroup>