From bdde191c1c79d86d43939435bec6a86c15d21041 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Tue, 20 Jan 2015 21:21:41 -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 | 77 +++++++++++++++++++++++++++---------------
 1 file changed, 50 insertions(+), 27 deletions(-)

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 947130753e0..85a6f394f01 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -828,19 +828,6 @@
        <entry><literal>0.785398163397448</literal></entry>
       </row>
 
-      <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>
-       <entry><literal>random()</literal></entry>
-       <entry></entry>
-      </row>
-
       <row>
        <entry>
         <indexterm>
@@ -862,20 +849,6 @@
        <entry><literal>42.44</literal></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>
-       <entry><literal>setseed(0.54823)</literal></entry>
-       <entry></entry>
-      </row>
-
       <row>
        <entry>
         <indexterm>
@@ -951,6 +924,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.39.5