random: Add description to the jumping methods of Xoshiro256StarStar (#1991)

* random: Add description to the jumping methods of Xoshiro256StarStar

* random: Improve explanation of Xoshiro jumping

Co-authored-by: George Peter Banyard <[email protected]>

Co-authored-by: George Peter Banyard <[email protected]>

Author: TimWolla

reference/random/random/engine/xoshiro256starstar/jump.xml

@@ -12,11 +12,17 @@
    <void />
   </methodsynopsis>
   <para>
-
+   Moves the algorithm’s state ahead by 2<superscript>128</superscript> steps, as if
+   <function>Random\Engine\Xoshiro256StarStar::generate</function> was called
+   2<superscript>128</superscript> times.
+  </para>
+  <para>
+   The purpose of a jump is to facilitate the creation of a new <classname>Random\Engine\Xoshiro256StarStar</classname>
+   engine from an existing seeded <classname>Random\Engine\Xoshiro256StarStar</classname> engine.
+   The seeded engine acts as a blueprint, which can be <link linkend="language.oop5.cloning">cloned</link>
+   and repeatedly jumped to create 2<superscript>128</superscript> non-overlapping sequences with
+   2<superscript>128</superscript> values each.
   </para>
-
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -53,6 +59,12 @@
   </example>
  </refsect1>
 
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><function>Random\Engine\Xoshiro256StarStar::jumpLong</function></member>
+  </simplelist>
+ </refsect1>
 
 </refentry>
 <!-- Keep this comment at the end of the file

reference/random/random/engine/xoshiro256starstar/jumplong.xml

@@ -12,11 +12,22 @@
    <void />
   </methodsynopsis>
   <para>
-
+   Moves the algorithm’s state ahead by 2<superscript>192</superscript> steps, as if
+   <function>Random\Engine\Xoshiro256StarStar::generate</function> was called
+   2<superscript>192</superscript> times.
+  </para>
+  <para>
+   The purpose of a long jump is to facilitate the creation of a new <classname>Random\Engine\Xoshiro256StarStar</classname>
+   engine from an existing seeded <classname>Random\Engine\Xoshiro256StarStar</classname> engine.
+   The seeded engine acts as a blueprint, which can be <link linkend="language.oop5.cloning">cloned</link>
+   and repeatedly jumped to create 2<superscript>64</superscript> non-overlapping sequences with
+   2<superscript>192</superscript> values each.
+  </para>
+  <para>
+   Long jumping may be combined with <function>Random\Engine\Xoshiro256StarStar::jump</function>ing
+   to further split each of the 2<superscript>64</superscript> sequences generated by long jumping,
+   into 2<superscript>128</superscript> sequences of 2<superscript>64</superscript> values each.
   </para>
-
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -53,6 +64,12 @@
   </example>
  </refsect1>
 
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><function>Random\Engine\Xoshiro256StarStar::jump</function></member>
+  </simplelist>
+ </refsect1>
 
 </refentry>
 <!-- Keep this comment at the end of the file