From 8d87f624eb2f3b1d9b61d5b73292e1a6486b630c Mon Sep 17 00:00:00 2001
From: toasteater <48371905+toasteater@users.noreply.github.com>
Date: Tue, 2 Apr 2019 17:38:03 +0800
Subject: [PATCH] Improve RandomNumberGenerator docs.

Clarified behavior of a few methods. Added implementation notes so
that developers not familiar with RNGs are alerted to common pitfalls.

(cherry picked from commit ae1393acaef148c8e2d77f122ffef395e326d024)
---
 doc/classes/RandomNumberGenerator.xml | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/doc/classes/RandomNumberGenerator.xml b/doc/classes/RandomNumberGenerator.xml
index fff13402f14..51bc0086589 100644
--- a/doc/classes/RandomNumberGenerator.xml
+++ b/doc/classes/RandomNumberGenerator.xml
@@ -1,9 +1,10 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="RandomNumberGenerator" inherits="Reference" category="Core" version="3.1">
 	<brief_description>
-		A class for generation pseudo-random numbers.
+		A class for generating pseudo-random numbers.
 	</brief_description>
 	<description>
+		RandomNumberGenerator is a class for generating pseudo-random numbers. It currently uses PCG32. The underlying algorithm is an implementation detail. As a result, it should not be depended upon for reproducible random streams across Godot versions.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -14,7 +15,7 @@
 			<return type="float">
 			</return>
 			<description>
-				Generates pseudo-random float between '0.0' and '1.0'.
+				Generates pseudo-random float between '0.0' and '1.0', inclusive.
 			</description>
 		</method>
 		<method name="randf_range">
@@ -25,14 +26,14 @@
 			<argument index="1" name="to" type="float">
 			</argument>
 			<description>
-				Generates pseudo-random float between [code]from[/code] and [code]to[/code].
+				Generates pseudo-random float between [code]from[/code] and [code]to[/code], inclusive.
 			</description>
 		</method>
 		<method name="randi">
 			<return type="int">
 			</return>
 			<description>
-				Generates pseudo-random 32-bit unsigned integer between '0' and '4294967295'.
+				Generates pseudo-random 32-bit unsigned integer between '0' and '4294967295', inclusive.
 			</description>
 		</method>
 		<method name="randi_range">
@@ -57,6 +58,7 @@
 	<members>
 		<member name="seed" type="int" setter="set_seed" getter="get_seed">
 			The seed used by the random number generator. A given seed will give a reproducible sequence of pseudo-random numbers.
+			[b]Note:[/b] The RNG does not have an avalanche effect, and can output similar random streams given similar seeds. Consider using a hash function to improve your seed quality if they're sourced externally.
 		</member>
 	</members>
 	<constants>