1 files changed, 73 insertions, 0 deletions
diff --git a/docs/source/lang/api/random.rst b/docs/source/lang/api/random.rst
new file mode 100644
index 0000000..dd8871d
--- /dev/null
+++ b/docs/source/lang/api/random.rst
@@ -0,0 +1,73 @@
+.. highlight:: cpp
+
+.. _lang-random:
+
+random()
+========
+
+The ``random()`` function generates pseudo-random numbers.
+
+Library Documentation
+---------------------
+
+.. FIXME keep tracking Sphinx/Breathe's ability to reference
+.. overloaded functions so we can use doxygenfunction instead of
+.. manually documenting.
+
+.. cpp:function:: random(long max)
+
+   Same as a call to ``random(0, max)``.
+
+.. cpp:function:: random(long min, long max)
+
+   Generate a pseudo-random number with given lower and upper bounds.
+
+   *Parameters*
+
+   - ``min`` - Lower bound on the returned value, inclusive
+   - ``max`` - Upper bound on the returned value, exclusive
+
+   *Returns*: A pseudo-random number in the range [min, max).
+
+Discussion
+----------
+
+If it is important for a sequence of values generated by
+:ref:`random() <lang-random>` to differ, on subsequent executions of a
+sketch, use :ref:`randomSeed() <lang-randomseed>` to initialize the
+random number generator with a fairly random input, such as
+:ref:`analogRead() <lang-analogread>` on an unconnected pin.
+
+Conversely, it can occasionally be useful to use pseudorandom
+sequences that repeat exactly. This can be accomplished by calling
+``randomSeed()`` with a fixed number, before starting the random
+sequence.
+
+Example
+-------
+
+The following sketch initializes the random seed based on an :ref:`ADC
+<adc>` reading of pin 0.  If this pin is unconnected, the Sketch
+should print different values to the :ref:`serial monitor
+<ide-serial-monitor>` each time it is run::
+
+    long randNumber;
+
+    void setup() {
+      pinMode(0, INPUT_ANALOG);
+      randomSeed(analogRead(0));
+    }
+
+    void loop() {
+      randNumber = random(300);
+      SerialUSB.println(randNumber);
+
+      delay(50);
+    }
+
+See Also
+--------
+
+-  :ref:`randomSeed() <lang-randomseed>`
+
+.. include:: cc-attribution.txt