From 902289d7dd083ef2ba454c465bc4349a877fc23e Mon Sep 17 00:00:00 2001
From: Bob Nystrom <robert@stuffwithstuff.com>
Date: Mon, 9 Nov 2015 07:37:06 -0800
Subject: [PATCH] Document the "random" module.

---
 doc/site/modules/core/index.markdown      |  2 +-
 doc/site/modules/core/template.html       |  4 +-
 doc/site/modules/index.markdown           | 12 +--
 doc/site/modules/io/index.markdown        |  2 +-
 doc/site/modules/io/template.html         |  4 +-
 doc/site/modules/meta/index.markdown      |  2 +-
 doc/site/modules/meta/template.html       |  4 +-
 doc/site/modules/random/index.markdown    |  9 ++-
 doc/site/modules/random/random.markdown   | 92 ++++++++++++++++++++++-
 doc/site/modules/random/template.html     |  4 +-
 doc/site/modules/scheduler/index.markdown |  2 +-
 doc/site/modules/scheduler/template.html  |  4 +-
 doc/site/modules/timer/index.markdown     |  2 +-
 doc/site/modules/timer/template.html      |  4 +-
 src/optional/wren_opt_random.wren         |  8 +-
 src/optional/wren_opt_random.wren.inc     |  8 +-
 16 files changed, 128 insertions(+), 35 deletions(-)

diff --git a/doc/site/modules/core/index.markdown b/doc/site/modules/core/index.markdown
index 2b1e17ae..727bbf14 100644
--- a/doc/site/modules/core/index.markdown
+++ b/doc/site/modules/core/index.markdown
@@ -1,4 +1,4 @@
-^title Core Module
+^title Module "core"
 
 Because Wren is designed for [embedding in applications][embedding], its core
 module is minimal and is focused on working with objects within Wren. For
diff --git a/doc/site/modules/core/template.html b/doc/site/modules/core/template.html
index 6674caf1..206c47a0 100644
--- a/doc/site/modules/core/template.html
+++ b/doc/site/modules/core/template.html
@@ -22,7 +22,7 @@
   <nav class="big">
     <ul>
       <li><a href="../">Modules</a></li>
-      <li><a href="./">Core</a></li>
+      <li><a href="./">core</a></li>
     </ul>
     <section>
       <h2>core classes</h2>
@@ -47,7 +47,7 @@
     <table>
       <tr>
         <td><a href="../">Modules</a></td>
-        <td><a href="./">Core</a></td>
+        <td><a href="./">core</a></td>
       </tr>
       <tr>
         <td colspan="2"><h2>core classes</h2></td>
diff --git a/doc/site/modules/index.markdown b/doc/site/modules/index.markdown
index 6cb7c8f8..93803874 100644
--- a/doc/site/modules/index.markdown
+++ b/doc/site/modules/index.markdown
@@ -16,7 +16,7 @@ built directly into the language itself: [numbers][], [strings][], etc.
 
 The core module is always available and can't be removed.
 
-* [Core](core)
+* [core](core)
 
 ## Optional
 
@@ -31,8 +31,8 @@ possible.
 
 There are a couple of optional modules:
 
-* [Meta](meta)
-* [Random](random)
+* [meta](meta)
+* [random](random)
 
 ## CLI
 
@@ -43,6 +43,6 @@ applications that want to embed Wren.
 
 [libuv]: http://libuv.org
 
-* [IO](io)
-* [Scheduler](scheduler)
-* [Timer](timer)
+* [io](io)
+* [scheduler](scheduler)
+* [timer](timer)
diff --git a/doc/site/modules/io/index.markdown b/doc/site/modules/io/index.markdown
index 84ece012..ba41efbd 100644
--- a/doc/site/modules/io/index.markdown
+++ b/doc/site/modules/io/index.markdown
@@ -1,4 +1,4 @@
-^title IO Module
+^title Module "io"
 
 **TODO**
 
diff --git a/doc/site/modules/io/template.html b/doc/site/modules/io/template.html
index 756eadea..ab36a796 100644
--- a/doc/site/modules/io/template.html
+++ b/doc/site/modules/io/template.html
@@ -22,7 +22,7 @@
   <nav class="big">
     <ul>
       <li><a href="../">Modules</a></li>
-      <li><a href="./">IO</a></li>
+      <li><a href="./">io</a></li>
     </ul>
     <section>
       <h2>io classes</h2>
@@ -36,7 +36,7 @@
     <table>
       <tr>
         <td><a href="../">Modules</a></td>
-        <td><a href="./">IO</a></td>
+        <td><a href="./">io</a></td>
       </tr>
       <tr>
         <td colspan="2"><h2>io classes</h2></td>
diff --git a/doc/site/modules/meta/index.markdown b/doc/site/modules/meta/index.markdown
index 79a0a69e..924e2b27 100644
--- a/doc/site/modules/meta/index.markdown
+++ b/doc/site/modules/meta/index.markdown
@@ -1,4 +1,4 @@
-^title Meta Module
+^title Module "meta"
 
 **TODO**
 
diff --git a/doc/site/modules/meta/template.html b/doc/site/modules/meta/template.html
index 6e7f3383..02e77650 100644
--- a/doc/site/modules/meta/template.html
+++ b/doc/site/modules/meta/template.html
@@ -22,7 +22,7 @@
   <nav class="big">
     <ul>
       <li><a href="../">Modules</a></li>
-      <li><a href="./">Meta</a></li>
+      <li><a href="./">meta</a></li>
     </ul>
     <section>
       <h2>meta classes</h2>
@@ -35,7 +35,7 @@
     <table>
       <tr>
         <td><a href="../">Modules</a></td>
-        <td><a href="./">Meta</a></td>
+        <td><a href="./">meta</a></td>
       </tr>
       <tr>
         <td colspan="2"><h2>meta classes</h2></td>
diff --git a/doc/site/modules/random/index.markdown b/doc/site/modules/random/index.markdown
index 9b0c6ede..2ebd3c20 100644
--- a/doc/site/modules/random/index.markdown
+++ b/doc/site/modules/random/index.markdown
@@ -1,5 +1,10 @@
-^title Random Module
+^title Module "random"
 
-**TODO**
+This module provides a simple, fast pseudo-random number generator.
+
+It is an optional module. You can omit it from your application by setting the
+preprocessor constant `WREN_OPT_RANDOM` to `0`.
+
+It contains a single class:
 
 * [Random](random.html)
diff --git a/doc/site/modules/random/random.markdown b/doc/site/modules/random/random.markdown
index 363b6e76..db333ddb 100644
--- a/doc/site/modules/random/random.markdown
+++ b/doc/site/modules/random/random.markdown
@@ -1,7 +1,95 @@
 ^title Random Class
 
-**TODO**
+A simple, fast pseudo-random number generator. Internally, it uses the [well
+equidistributed long-period linear PRNG][well] (WELL512a).
+
+[well]: https://en.wikipedia.org/wiki/Well_equidistributed_long-period_linear
+
+Each instance of the class generates a sequence of randomly distributed numbers
+based on the internal state of the object. The state is initialized from a
+*seed*. Two instances with the same seed generate the exact same sequence of
+numbers.
+
+
+It must be imported from the [random][] module:
+
+    :::wren
+    import "random" for Random
+
+[random]: ../
+
+## Constructors
+
+### Random.**new**()
+
+Creates a new generator whose state is seeded based on the current time.
+
+    :::wren
+    var random = Random.new()
+
+### Random.**new**(seed)
+
+Creates a new generator initialized with [seed]. The seed can either be a
+number, or a non-empty sequence of numbers. If the sequnce has more than 16
+elements, only the first 16 are used. If it has fewer, the elements are cycled
+to generate 16 seed values.
+
+    :::wren
+    Random.new(12345)
+    Random.new("appleseed".codePoints)
 
 ## Methods
 
-**TODO**
+### **float**()
+
+Returns a floating point value between 0.0 and 1.0, including 0.0, but excluding
+1.0.
+
+    :::wren
+    var random = Random.new(12345)
+    System.print(random.float()) //> 0.53178795980617
+    System.print(random.float()) //> 0.20180515043262
+    System.print(random.float()) //> 0.43371948658705
+
+### **float**(end)
+
+Returns a floating point value between 0.0 and `end`, including 0.0 but
+excluding `end`.
+
+    :::wren
+    var random = Random.new(12345)
+    System.print(random.float(0))     //> 0
+    System.print(random.float(100))   //> 20.180515043262
+    System.print(random.float(-100))  //> -43.371948658705
+
+### **float**(start, end)
+
+Returns a floating point value between `start` and `end`, including `start` but
+excluding `end`.
+
+    :::wren
+    var random = Random.new(12345)
+    System.print(random.float(3, 4))    //> 3.5317879598062
+    System.print(random.float(-10, 10)) //> -5.9638969913476
+    System.print(random.float(-4, 2))   //> -1.3976830804777
+
+### **int**(end)
+
+Returns an integer between 0 and `end`, including 0 but excluding `end`.
+
+    :::wren
+    var random = Random.new(12345)
+    System.print(random.int(1))    //> 0
+    System.print(random.int(10))   //> 2
+    System.print(random.int(-50))  //> -22
+
+### **int**(start, end)
+
+Returns an integer between `start` and `end`, including `start` but excluding
+`end`.
+
+    :::wren
+    var random = Random.new(12345)
+    System.print(random.int(3, 4))    //> 3
+    System.print(random.int(-10, 10)) //> -6
+    System.print(random.int(-4, 2))   //> -2
diff --git a/doc/site/modules/random/template.html b/doc/site/modules/random/template.html
index 95c939d9..9bb3fa8f 100644
--- a/doc/site/modules/random/template.html
+++ b/doc/site/modules/random/template.html
@@ -22,7 +22,7 @@
   <nav class="big">
     <ul>
       <li><a href="../">Modules</a></li>
-      <li><a href="./">Random</a></li>
+      <li><a href="./">random</a></li>
     </ul>
     <section>
       <h2>random classes</h2>
@@ -35,7 +35,7 @@
     <table>
       <tr>
         <td><a href="../">Modules</a></td>
-        <td><a href="./">Random</a></td>
+        <td><a href="./">random</a></td>
       </tr>
       <tr>
         <td colspan="2"><h2>random classes</h2></td>
diff --git a/doc/site/modules/scheduler/index.markdown b/doc/site/modules/scheduler/index.markdown
index 8e685488..19c60d5b 100644
--- a/doc/site/modules/scheduler/index.markdown
+++ b/doc/site/modules/scheduler/index.markdown
@@ -1,4 +1,4 @@
-^title Scheduler Module
+^title Module "scheduler"
 
 **TODO**
 
diff --git a/doc/site/modules/scheduler/template.html b/doc/site/modules/scheduler/template.html
index 5f1b3f88..f67d8940 100644
--- a/doc/site/modules/scheduler/template.html
+++ b/doc/site/modules/scheduler/template.html
@@ -22,7 +22,7 @@
   <nav class="big">
     <ul>
       <li><a href="../">Modules</a></li>
-      <li><a href="./">Scheduler</a></li>
+      <li><a href="./">scheduler</a></li>
     </ul>
     <section>
       <h2>scheduler classes</h2>
@@ -35,7 +35,7 @@
     <table>
       <tr>
         <td><a href="../">Modules</a></td>
-        <td><a href="./">Scheduler</a></td>
+        <td><a href="./">scheduler</a></td>
       </tr>
       <tr>
         <td colspan="2"><h2>scheduler classes</h2></td>
diff --git a/doc/site/modules/timer/index.markdown b/doc/site/modules/timer/index.markdown
index d02a9a3a..64bdaff4 100644
--- a/doc/site/modules/timer/index.markdown
+++ b/doc/site/modules/timer/index.markdown
@@ -1,4 +1,4 @@
-^title Timer Module
+^title Module "timer"
 
 **TODO**
 
diff --git a/doc/site/modules/timer/template.html b/doc/site/modules/timer/template.html
index e44c6c48..8d8c84c4 100644
--- a/doc/site/modules/timer/template.html
+++ b/doc/site/modules/timer/template.html
@@ -22,7 +22,7 @@
   <nav class="big">
     <ul>
       <li><a href="../">Modules</a></li>
-      <li><a href="./">Timer</a></li>
+      <li><a href="./">timer</a></li>
     </ul>
     <section>
       <h2>timer classes</h2>
@@ -35,7 +35,7 @@
     <table>
       <tr>
         <td><a href="../">Modules</a></td>
-        <td><a href="./">Timer</a></td>
+        <td><a href="./">timer</a></td>
       </tr>
       <tr>
         <td colspan="2"><h2>timer classes</h2></td>
diff --git a/src/optional/wren_opt_random.wren b/src/optional/wren_opt_random.wren
index 246d5660..559200df 100644
--- a/src/optional/wren_opt_random.wren
+++ b/src/optional/wren_opt_random.wren
@@ -40,10 +40,10 @@ foreign class Random {
   foreign seed_(n1, n2, n3, n4, n5, n6, n7, n8, n9, n10, n11, n12, n13, n14, n15, n16)
 
   foreign float()
-  float(max) { float() * max }
-  float(min, max) { float() * (max - min) + min }
+  float(end) { float() * end }
+  float(start, end) { float() * (end - start) + start }
 
   foreign int()
-  int(max) { (float() * max).floor }
-  int(min, max) { (float() * (max - min)).floor + min }
+  int(end) { (float() * end).floor }
+  int(start, end) { (float() * (end - start)).floor + start }
 }
diff --git a/src/optional/wren_opt_random.wren.inc b/src/optional/wren_opt_random.wren.inc
index 2b1e88ad..7bb61512 100644
--- a/src/optional/wren_opt_random.wren.inc
+++ b/src/optional/wren_opt_random.wren.inc
@@ -42,10 +42,10 @@ static const char* randomModuleSource =
 "  foreign seed_(n1, n2, n3, n4, n5, n6, n7, n8, n9, n10, n11, n12, n13, n14, n15, n16)\n"
 "\n"
 "  foreign float()\n"
-"  float(max) { float() * max }\n"
-"  float(min, max) { float() * (max - min) + min }\n"
+"  float(end) { float() * end }\n"
+"  float(start, end) { float() * (end - start) + start }\n"
 "\n"
 "  foreign int()\n"
-"  int(max) { (float() * max).floor }\n"
-"  int(min, max) { (float() * (max - min)).floor + min }\n"
+"  int(end) { (float() * end).floor }\n"
+"  int(start, end) { (float() * (end - start)).floor + start }\n"
 "}\n";