Improve documentation of random() function.

tglsfdc · tglsfdc · commit a113a66a7a7d · 2015-01-20T21:21:47.000-05:00
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 75fdcec into all supported versions, per discussion of the need to document that random() is just a wrapper around random(3).
diff --git 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
