From af6dcad33722cfc8ba8513084f5c847351fd140c Mon Sep 17 00:00:00 2001
From: Christian Klaussner <developer@klaussner.me>
Date: Tue, 14 Jun 2016 19:34:40 +0200
Subject: [PATCH] Add documentation for Random functions

---
 packages/random/random.js | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/packages/random/random.js b/packages/random/random.js
index c62b50b732..91e261bbe7 100644
--- a/packages/random/random.js
+++ b/packages/random/random.js
@@ -129,6 +129,11 @@ RandomGenerator.Type = {
   ALEA: "ALEA",
 };
 
+/**
+ * @name Random.fraction
+ * @summary Return a number between 0 and 1, like `Math.random`.
+ * @locus Anywhere
+ */
 RandomGenerator.prototype.fraction = function () {
   var self = this;
   if (self.type === RandomGenerator.Type.ALEA) {
@@ -145,6 +150,12 @@ RandomGenerator.prototype.fraction = function () {
   }
 };
 
+/**
+ * @name Random.hexString
+ * @summary Return a random string of `n` hexadecimal digits.
+ * @locus Anywhere
+ * @param {Number} n Length of the string
+ */
 RandomGenerator.prototype.hexString = function (digits) {
   var self = this;
   if (self.type === RandomGenerator.Type.NODE_CRYPTO) {
@@ -177,6 +188,14 @@ RandomGenerator.prototype._randomString = function (charsCount,
   return digits.join("");
 };
 
+/**
+ * @name Random.id
+ * @summary Return a unique identifier, such as `"Jjwjg6gouWLXhMGKW"`, that is
+ * likely to be unique in the whole world.
+ * @locus Anywhere
+ * @param {Number} [n] Optional length of the identifier in characters
+ *   (defaults to 17)
+ */
 RandomGenerator.prototype.id = function (charsCount) {
   var self = this;
   // 17 characters is around 96 bits of entropy, which is the amount of
@@ -187,6 +206,15 @@ RandomGenerator.prototype.id = function (charsCount) {
   return self._randomString(charsCount, UNMISTAKABLE_CHARS);
 };
 
+/**
+ * @name Random.secret
+ * @summary Return a random string of printable characters with 6 bits of
+ * entropy per character. Use `Random.secret` for security-critical secrets
+ * that are intended for machine, rather than human, consumption.
+ * @locus Anywhere
+ * @param {Number} [n] Optional length of the secret string (defaults to 43
+ *   characters, or 256 bits of entropy)
+ */
 RandomGenerator.prototype.secret = function (charsCount) {
   var self = this;
   // Default to 256 bits of entropy, or 43 characters at 6 bits per
@@ -196,6 +224,12 @@ RandomGenerator.prototype.secret = function (charsCount) {
   return self._randomString(charsCount, BASE64_CHARS);
 };
 
+/**
+ * @name Random.choice
+ * @summary Return a random element of the given array or string.
+ * @locus Anywhere
+ * @param {Array|String} arrayOrString Array or string to choose from
+ */
 RandomGenerator.prototype.choice = function (arrayOrString) {
   var index = Math.floor(this.fraction() * arrayOrString.length);
   if (typeof arrayOrString === "string")