From a113a66a7a7dc28d176663067b5edc9065de2c71 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Tue, 20 Jan 2015 21:21:47 -0500
Subject: [PATCH] Improve documentation of random() function.

Move random() and setseed() to a separate table, to have them grouped
together. Also add a notice that random() is not cryptographically secure.

Back-patch of commit 75fdcec14543b60cc0c67483d8cc47d5c7adf1a8 into
all supported versions, per discussion of the need to document that
random() is just a wrapper around random(3).
---
 doc/src/sgml/func.sgml | 73 +++++++++++++++++++++++++++++-------------
 1 file changed, 50 insertions(+), 23 deletions(-)

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 2d6f500b4c..71bdfb09cd 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -650,15 +650,9 @@
    <indexterm>
     <primary>radians</primary>
    </indexterm>
-   <indexterm>
-    <primary>random</primary>
-   </indexterm>
    <indexterm>
     <primary>round</primary>
    </indexterm>
-   <indexterm>
-    <primary>setseed</primary>
-   </indexterm>
    <indexterm>
     <primary>sign</primary>
    </indexterm>
@@ -819,14 +813,6 @@
        <entry><literal>0.785398163397448</literal></entry>
       </row>
 
-      <row>
-       <entry><literal><function>random()</function></literal></entry>
-       <entry><type>dp</type></entry>
-       <entry>random value in the range 0.0 &lt;= x &lt; 1.0</entry>
-       <entry><literal>random()</literal></entry>
-       <entry></entry>
-      </row>
-
       <row>
        <entry><literal><function>round(<type>dp</type> or <type>numeric</type>)</function></literal></entry>
        <entry>(same as input)</entry>
@@ -843,15 +829,6 @@
        <entry><literal>42.44</literal></entry>
       </row>
 
-      <row>
-       <entry><literal><function>setseed(<type>dp</type>)</function></literal></entry>
-       <entry><type>void</type></entry>
-       <entry>set seed for subsequent <literal>random()</literal> calls (value between -1.0 and
-       1.0, inclusive)</entry>
-       <entry><literal>setseed(0.54823)</literal></entry>
-       <entry></entry>
-      </row>
-
       <row>
        <entry><literal><function>sign(<type>dp</type> or <type>numeric</type>)</function></literal></entry>
        <entry>(same as input)</entry>
@@ -907,6 +884,56 @@
     </tgroup>
    </table>
 
+  <para>
+    <xref linkend="functions-math-random-table"> shows functions for
+    generating random numbers.
+  </para>
+
+   <table id="functions-math-random-table">
+    <title>Random Functions</title>
+
+    <tgroup cols="3">
+     <thead>
+      <row>
+       <entry>Function</entry>
+       <entry>Return Type</entry>
+       <entry>Description</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>
+        <indexterm>
+         <primary>random</primary>
+        </indexterm>
+        <literal><function>random()</function></literal>
+       </entry>
+       <entry><type>dp</type></entry>
+       <entry>random value in the range 0.0 &lt;= x &lt; 1.0</entry>
+      </row>
+
+      <row>
+       <entry>
+        <indexterm>
+         <primary>setseed</primary>
+        </indexterm>
+        <literal><function>setseed(<type>dp</type>)</function></literal>
+       </entry>
+       <entry><type>void</type></entry>
+       <entry>set seed for subsequent <literal>random()</literal> calls (value between -1.0 and
+       1.0, inclusive)</entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </table>
+
+  <para>
+   The characteristics of the values returned by
+   <literal><function>random()</function></literal> depend
+   on the system implementation. It is not suitable for cryptographic
+   applications; see <xref linkend="pgcrypto"> module for an alternative.
+   </para>
+
   <para>
    Finally, <xref linkend="functions-math-trig-table"> shows the
    available trigonometric functions.  All trigonometric functions
-- 
2.40.0