[DOC-CVS] [doc-en] master: Fixed #4800: Check examples in the 'random' section of the manual
[email protected] (Derick Rethans)
| Newsgroups | php.doc.cvs |
|---|---|
| Message-ID | <[email protected]> |
Author: Derick Rethans (derickr)
Date: 2025-08-04T16:40:42+01:00
Commit: https://github.com/php/doc-en/commit/1bcc40f8134305cbebf6c8378ee7e5fc8c569674
Raw diff: https://github.com/php/doc-en/commit/1bcc40f8134305cbebf6c8378ee7e5fc8c569674.diff
Fixed #4800: Check examples in the 'random' section of the manual
Changed paths:
M reference/random/book.xml
M reference/random/examples.xml
M reference/random/random/engine/mt19937/construct.xml
M reference/random/random/engine/pcgoneseq128xslrr64/construct.xml
M reference/random/random/engine/xoshiro256starstar/construct.xml
M reference/random/random/randomizer/construct.xml
M reference/random/random/randomizer/getint.xml
M reference/random/random/randomizer/nextint.xml
M reference/reflection/book.xml
Diff:
diff --git a/reference/random/book.xml b/reference/random/book.xml
index 7ebac831c95c..8909943a5cc9 100644
--- a/reference/random/book.xml
+++ b/reference/random/book.xml
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
-<book xml:id="book.random" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+<book xml:id="book.random" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" annotations="interactive">
<?phpdoc extension-membership="core" ?>
<title>Random Number Generators and Functions Related to Randomness</title>
<titleabbrev>Random</titleabbrev>
diff --git a/reference/random/examples.xml b/reference/random/examples.xml
index 3341a7146afa..dcf16dc60108 100644
--- a/reference/random/examples.xml
+++ b/reference/random/examples.xml
@@ -6,16 +6,38 @@
<programlisting role="php">
<![CDATA[
<?php
+$r = new \Random\Randomizer();
-/* ... */
+// Generating a random domain name
+printf(
+ "%s.example.com\n",
+ $r->getBytesFromString('abcdefghijklmnopqrstuvwxyz0123456789', 16)
+);
+// Shuffle array:
+$fruits = [ 'red' => '🍎', 'green' => '🥝', 'yellow' => '🍌', 'pink' => '🍑', 'purple' => '🍇' ];
+echo "Salad: ", implode(', ', $r->shuffleArray($fruits)), "\n";
+
+// Shuffeling array keys
+$fruits = [ 'red' => '🍎', 'green' => '🥝', 'yellow' => '🍌', 'pink' => '🍑', 'purple' => '🍇' ];
+
+$keys = $r->pickArrayKeys($fruits, 2);
+// Look up the values for the picked keys.
+$selection = array_map(
+ static fn ($key) => $fruits[$key],
+ $keys
+);
+
+echo "Values: ", implode(', ', $selection), "\n";
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
-...
+j87fzv1p0daiwmlo.example.com
+Salad: 🥝, 🍇, 🍎, 🍌, 🍑
+Values: 🍌, 🍑
]]>
</screen>
</example>
diff --git a/reference/random/random/engine/mt19937/construct.xml b/reference/random/random/engine/mt19937/construct.xml
index 51ad9025b60f..28878f8da07b 100644
--- a/reference/random/random/engine/mt19937/construct.xml
+++ b/reference/random/random/engine/mt19937/construct.xml
@@ -17,9 +17,6 @@
</para>
&caution.mt19937-tiny-seed;
-
- &warn.undocumented.func;
-
</refsect1>
<refsect1 role="parameters">
@@ -77,7 +74,7 @@
<refsect1 role="examples">
&reftitle.examples;
- <example>
+ <example annotations="non-interactive">
<title><function>Random\Engine\Mt19937::__construct</function> example</title>
<programlisting role="php">
<![CDATA[
diff --git a/reference/random/random/engine/pcgoneseq128xslrr64/construct.xml b/reference/random/random/engine/pcgoneseq128xslrr64/construct.xml
index 82ad09b30edc..664b215ac362 100644
--- a/reference/random/random/engine/pcgoneseq128xslrr64/construct.xml
+++ b/reference/random/random/engine/pcgoneseq128xslrr64/construct.xml
@@ -14,9 +14,6 @@
<para>
</para>
-
- &warn.undocumented.func;
-
</refsect1>
<refsect1 role="parameters">
@@ -92,7 +89,7 @@
<refsect1 role="examples">
&reftitle.examples;
- <example>
+ <example annotations="non-interactive">
<title><function>Random\Engine\PcgOneseq128XslRr64::__construct</function> example</title>
<programlisting role="php">
<![CDATA[
diff --git a/reference/random/random/engine/xoshiro256starstar/construct.xml b/reference/random/random/engine/xoshiro256starstar/construct.xml
index 68dc9b3e5eba..744eedd7c5db 100644
--- a/reference/random/random/engine/xoshiro256starstar/construct.xml
+++ b/reference/random/random/engine/xoshiro256starstar/construct.xml
@@ -14,9 +14,6 @@
<para>
</para>
-
- &warn.undocumented.func;
-
</refsect1>
<refsect1 role="parameters">
@@ -98,7 +95,7 @@
<refsect1 role="examples">
&reftitle.examples;
- <example>
+ <example annotations="non-interactive">
<title><function>Random\Engine\Xoshiro256StarStar::__construct</function> example</title>
<programlisting role="php">
<![CDATA[
diff --git a/reference/random/random/randomizer/construct.xml b/reference/random/random/randomizer/construct.xml
index eeed6b7651ba..b7edb3262c4e 100644
--- a/reference/random/random/randomizer/construct.xml
+++ b/reference/random/random/randomizer/construct.xml
@@ -37,37 +37,18 @@
</variablelist>
</refsect1>
- <!-- Return values commented out, as constructors generally don't return a
- value. Uncomment this if you do need a return values section (for
- example, because there's also a procedural version of the method).
- <refsect1 role="returnvalues">
- &reftitle.returnvalues;
- <para>
-
- </para>
- </refsect1>
- -->
-
-
<refsect1 role="examples">
&reftitle.examples;
- <example>
+ <example annotations="non-interactive">
<title><function>Random\Randomizer::__construct</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
-
-/* ... */
-
+$r = new \Random\Randomizer();
+$r = new \Random\Randomizer(new \Random\Engine\Mt19937());
?>
]]>
</programlisting>
- &example.outputs.similar;
- <screen>
-<![CDATA[
-...
-]]>
- </screen>
</example>
</refsect1>
diff --git a/reference/random/random/randomizer/getint.xml b/reference/random/random/randomizer/getint.xml
index e606dbaf4828..ae3a4b7d202d 100644
--- a/reference/random/random/randomizer/getint.xml
+++ b/reference/random/random/randomizer/getint.xml
@@ -15,9 +15,6 @@
<para>
</para>
-
- &warn.undocumented.func;
-
</refsect1>
<refsect1 role="parameters">
diff --git a/reference/random/random/randomizer/nextint.xml b/reference/random/random/randomizer/nextint.xml
index 9406bfd39d14..4ff81fd64c11 100644
--- a/reference/random/random/randomizer/nextint.xml
+++ b/reference/random/random/randomizer/nextint.xml
@@ -14,9 +14,6 @@
<para>
</para>
-
- &warn.undocumented.func;
-
</refsect1>
<refsect1 role="parameters">
diff --git a/reference/reflection/book.xml b/reference/reflection/book.xml
index 409e53b395ee..71ce2987594b 100644
--- a/reference/reflection/book.xml
+++ b/reference/reflection/book.xml
@@ -1,7 +1,7 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
-<book xml:id="book.reflection" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+<book xml:id="book.reflection" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" annotations="interactive">
<?phpdoc extension-membership="core" ?>
<title>Reflection</title>
<titleabbrev>Reflection</titleabbrev>