[prev in list] [next in list] [prev in thread] [next in thread]
List: php-doc-cvs
Subject: [DOC-CVS] [doc-en] master: Extend ext/random documentation (#1920)
From: Tim_Düsterhus_via_GitHub <noreply () php ! net>
Date: 2022-10-30 13:52:28
Message-ID: UUjedJYsEvhPFWneJSNMpvpQ7pE3y63YICf2lrz3k () main ! php ! net
[Download RAW message or body]
Author: Tim Düsterhus (TimWolla)
Committer: GitHub (web-flow)
Pusher: TimWolla
Date: 2022-10-30T14:58:54+01:00
Commit: https://github.com/php/doc-en/commit/4b1b9be99eba5fbce2de1190b5eba692bf09da11
Raw diff: https://github.com/php/doc-en/commit/4b1b9be99eba5fbce2de1190b5eba692bf09da11.diff
Extend ext/random documentation (#1920)
* random: Fix Randomizer::__construct()'s default value
The parameter is nullable and the actual default value should rather be
considered `null`. `null` is then *internally* replaced with a new instance of
`Random\Engine\Secure`.
* random: Document Randomizer::__construct()'s parameters
* random: Document Randomizer::getBytes()' parameter and return value
The phrasing is adapted from and synced with `random_bytes()`.
* random: Fix classname references for CSPRNG failures
* random: Unify phrasing random_int parameter description
* random: Document Randomizer::getInt()'s parameter and return value
The phrasing is adapted from and synced with `random_int()`.
* random: Add random.engineErrors snippets
This explains that the Randomizer's methods will pass through any Throwables
thrown by the engine.
* random: Fix definition of Randomizer::$engine
* random: Improve random_int/getInt parameter descriptions
Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>
* random: Improve random_int return value description
Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>
* random: Fix link to Randomizer::$engine property
Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>
* random: Use `&null;` entity in Randomizer::__construct()
Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>
Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>
Changed paths:
M language-snippets.ent
M reference/random/functions/random-bytes.xml
M reference/random/functions/random-int.xml
M reference/random/random.randomizer.xml
M reference/random/random/randomizer/construct.xml
M reference/random/random/randomizer/getbytes.xml
M reference/random/random/randomizer/getint.xml
Diff:
diff --git a/language-snippets.ent b/language-snippets.ent
index f07f52fa27a..59c820317a3 100644
--- a/language-snippets.ent
+++ b/language-snippets.ent
@@ -3737,7 +3737,7 @@ local: {
<listitem>
<simpara>
If none of the aforementioned sources are available, then a
- <classname>\Random\RandomException</classname> will be thrown.
+ <classname>Random\RandomException</classname> will be thrown.
</simpara>
</listitem>
</itemizedlist>
@@ -3746,7 +3746,7 @@ local: {
<listitem xmlns="http://docbook.org/ns/docbook">
<simpara>
If an appropriate source of randomness cannot be found,
- a <classname>\Random\RandomException</classname> will be thrown.
+ a <classname>Random\RandomException</classname> will be thrown.
</simpara>
</listitem>
<listitem xmlns="http://docbook.org/ns/docbook">
@@ -3766,6 +3766,15 @@ local: {
</note>
'>
+<!-- Random snippets -->
+<!ENTITY random.engineErrors '
+ <listitem xmlns="http://docbook.org/ns/docbook">
+ <simpara>
+ Any <classname>Throwable</classname>s thrown by the \
<methodname>Random\Engine::generate</methodname> method + of the underlying <link \
linkend="random-randomizer.props.engine"><literal>Random\Randomizer::$engine</literal></link>.
+ </simpara>
+ </listitem>
+'>
<!-- UOPZ snippets -->
diff --git a/reference/random/functions/random-bytes.xml \
b/reference/random/functions/random-bytes.xml index b4c71d8f164..4c201074079 100644
--- a/reference/random/functions/random-bytes.xml
+++ b/reference/random/functions/random-bytes.xml
@@ -28,7 +28,7 @@
<term><parameter>length</parameter></term>
<listitem>
<para>
- The length of the random string that should be returned in bytes.
+ The length of the random string that should be returned in bytes. Must be \
<literal>1</literal> or greater. </para>
</listitem>
</varlistentry>
@@ -49,8 +49,8 @@
&csprng.errors;
<listitem>
<simpara>
- If an invalid <parameter>length</parameter> of bytes is given, an
- <classname>Error</classname> will be thrown.
+ If the value of <parameter>length</parameter> is less than \
<literal>1</literal>, + a <classname>ValueError</classname> will be thrown.
</simpara>
</listitem>
</itemizedlist>
@@ -71,8 +71,8 @@
<entry>8.2.0</entry>
<entry>
In case of a <acronym>CSPRNG</acronym> failure, this function will now throw \
a
- <classname>\Random\RandomException</classname>. Previously a plain
- <classname>\Exception</classname> was thrown.
+ <classname>Random\RandomException</classname>. Previously a plain
+ <classname>Exception</classname> was thrown.
</entry>
</row>
</tbody>
diff --git a/reference/random/functions/random-int.xml \
b/reference/random/functions/random-int.xml index 76fe9098a85..cac96f688e2 100644
--- a/reference/random/functions/random-int.xml
+++ b/reference/random/functions/random-int.xml
@@ -30,8 +30,8 @@
<term><parameter>min</parameter></term>
<listitem>
<para>
- The lowest value to be returned, which must be
- <constant>PHP_INT_MIN</constant> or higher.
+ The lowest value to be returned; must be
+ <constant>PHP_INT_MIN</constant> or greater.
</para>
</listitem>
</varlistentry>
@@ -39,8 +39,8 @@
<term><parameter>max</parameter></term>
<listitem>
<para>
- The highest value to be returned, which must be less than or equal to
- <constant>PHP_INT_MAX</constant>.
+ The highest value to be returned; must be
+ <constant>PHP_INT_MAX</constant> or less.
</para>
</listitem>
</varlistentry>
@@ -50,8 +50,10 @@
<refsect1 role="returnvalues"><!-- {{{ -->
&reftitle.returnvalues;
<para>
- Returns a cryptographically secure random integer in the range
- <parameter>min</parameter> to <parameter>max</parameter>, inclusive.
+ Returns a cryptographically secure, uniformly selected integer from the closed \
interval + [<parameter>min</parameter>, <parameter>max</parameter>]. Both
+ <parameter>min</parameter> and <parameter>max</parameter> are
+ possible return values.
</para>
</refsect1><!-- }}} -->
@@ -62,7 +64,7 @@
<listitem>
<simpara>
If <parameter>max</parameter> is less than <parameter>min</parameter>, an
- <classname>Error</classname> will be thrown.
+ <classname>ValueError</classname> will be thrown.
</simpara>
</listitem>
</itemizedlist>
@@ -83,8 +85,8 @@
<entry>8.2.0</entry>
<entry>
In case of a <acronym>CSPRNG</acronym> failure, this function will now throw \
a
- <classname>\Random\RandomException</classname>. Previously a plain
- <classname>\Exception</classname> was thrown.
+ <classname>Random\RandomException</classname>. Previously a plain
+ <classname>Exception</classname> was thrown.
</entry>
</row>
</tbody>
diff --git a/reference/random/random.randomizer.xml \
b/reference/random/random.randomizer.xml index 378af106738..0ea49ad624d 100644
--- a/reference/random/random.randomizer.xml
+++ b/reference/random/random.randomizer.xml
@@ -33,7 +33,7 @@
<fieldsynopsis>
<modifier>public</modifier>
<modifier>readonly</modifier>
- <modifier>Engine</modifier>
+ <type>Random\Engine</type>
<varname linkend="random-randomizer.props.engine">engine</varname>
</fieldsynopsis>
diff --git a/reference/random/random/randomizer/construct.xml \
b/reference/random/random/randomizer/construct.xml index 930baebbdee..c7b4dcd6952 \
100644
--- a/reference/random/random/randomizer/construct.xml
+++ b/reference/random/random/randomizer/construct.xml
@@ -9,7 +9,7 @@
&reftitle.description;
<constructorsynopsis>
<modifier>public</modifier> \
<methodname>Random\Randomizer::__construct</methodname>
- <methodparam choice="opt"><type \
class="union"><type>Random\Engine</type><type>null</type></type><parameter>engine</parameter><initializer>new \
Random\Engine\Secure()</initializer></methodparam> + <methodparam \
choice="opt"><type class="union"><type>Random\Engine</type><type>null</type></type><parameter>engine</parameter><initializer>&null;</initializer></methodparam>
</constructorsynopsis>
<para>
@@ -26,7 +26,11 @@
<term><parameter>engine</parameter></term>
<listitem>
<para>
+ The <classname>Random\Engine</classname> to use to generate randomness.
+ </para>
+ <para>
+ If <parameter>engine</parameter> is omitted or &null;, a new \
<classname>Random\Engine\Secure</classname> object will be used. </para>
</listitem>
</varlistentry>
diff --git a/reference/random/random/randomizer/getbytes.xml \
b/reference/random/random/randomizer/getbytes.xml index e604fd1d326..2e1c496688c \
100644
--- a/reference/random/random/randomizer/getbytes.xml
+++ b/reference/random/random/randomizer/getbytes.xml
@@ -26,7 +26,7 @@
<term><parameter>length</parameter></term>
<listitem>
<para>
-
+ The length of the random string that should be returned in bytes. Must be \
<literal>1</literal> or greater. </para>
</listitem>
</varlistentry>
@@ -36,10 +36,23 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
-
+ Returns a string containing the requested number of random bytes.
</para>
</refsect1>
+ <refsect1 role="errors">
+ &reftitle.errors;
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ If the value of <parameter>length</parameter> is less than \
<literal>1</literal>, + a <classname>ValueError</classname> will be thrown.
+ </simpara>
+ </listitem>
+ &random.engineErrors;
+ </itemizedlist>
+ </refsect1>
+
<refsect1 role="examples">
&reftitle.examples;
<example>
@@ -62,6 +75,12 @@
</example>
</refsect1>
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><function>random_bytes</function></member>
+ </simplelist>
+ </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
diff --git a/reference/random/random/randomizer/getint.xml \
b/reference/random/random/randomizer/getint.xml index 00897d73f1b..4aaaf3d1c80 100644
--- a/reference/random/random/randomizer/getint.xml
+++ b/reference/random/random/randomizer/getint.xml
@@ -2,7 +2,7 @@
<refentry xml:id="random-randomizer.getint" xmlns="http://docbook.org/ns/docbook" \
xmlns:xlink="http://www.w3.org/1999/xlink"> <refnamediv>
<refname>Random\Randomizer::getInt</refname>
- <refpurpose>Get a uniformly chosen integer from an interval</refpurpose>
+ <refpurpose>Get a uniformly selected integer from a closed interval</refpurpose>
</refnamediv>
<refsect1 role="description">
@@ -27,7 +27,8 @@
<term><parameter>min</parameter></term>
<listitem>
<para>
-
+ The lowest value to be returned; must be
+ <constant>PHP_INT_MIN</constant> or greater.
</para>
</listitem>
</varlistentry>
@@ -35,7 +36,8 @@
<term><parameter>max</parameter></term>
<listitem>
<para>
-
+ The highest value to be returned; must be
+ <constant>PHP_INT_MAX</constant> or less.
</para>
</listitem>
</varlistentry>
@@ -45,10 +47,26 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
-
+ Returns an uniformly selected integer from the closed interval
+ [<parameter>min</parameter>, <parameter>max</parameter>]. Both
+ <parameter>min</parameter> and <parameter>max</parameter> are
+ possible return values.
</para>
</refsect1>
+ <refsect1 role="errors">
+ &reftitle.errors;
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ If <parameter>max</parameter> is less than <parameter>min</parameter>, a
+ <classname>ValueError</classname> will be thrown.
+ </simpara>
+ </listitem>
+ &random.engineErrors;
+ </itemizedlist>
+ </refsect1>
+
<refsect1 role="examples">
&reftitle.examples;
<example>
@@ -71,6 +89,12 @@
</example>
</refsect1>
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><function>random_int</function></member>
+ </simplelist>
+ </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
--
PHP Documentation Commits Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic