docs(random): Adds jsdocs to all random component files

src/random/charsets.ts

@@ -1,7 +1,36 @@
+/**
+ * Common charsets used for psuedo-random string generation.
+ *
+ * Copyright (c) 2018 Joseph R Cowman
+ * Licensed under MIT License (see https://github.com/regal/regal)
+ */
+
+// tslint:disable-next-line
+true; // This does nothing; it's only so the jsdocs won't conflict
+
+/**
+ * Contains all letters (upper- and lower-case), numbers, and some special characters.
+ * Used for psuedo-random string generation.
+ */
 export const EXPANDED_CHARSET =
     "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789~!@#$%^&*()-_=+{}[]|;:<>,.?";
+
+/**
+ * Contains all letters (upper- and lower-case) and numbers.
+ * Used for psuedo-random string generation.
+ */
 export const ALHPANUMERIC_CHARSET =
     "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+
+/**
+ * Contains all letters (upper- and lower-case).
+ * Used for psuedo-random string generation.
+ */
 export const ALPHABET_CHARSET =
     "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+
+/**
+ * Contains all numbers.
+ * Used for psuedo-random string generation.
+ */
 export const NUMBERS_CHARSET = "0123456789";

src/random/func/generate-seed.ts

@@ -1,9 +1,22 @@
+/**
+ * Contains generateSeed function and related configuration.
+ *
+ * Copyright (c) 2018 Joseph R Cowman
+ * Licensed under MIT License (see https://github.com/regal/regal)
+ */
+
 import Prando from "prando";
 import { EXPANDED_CHARSET } from "../charsets";
 
-// This results in 89^10 possible seeds
+// Note: the following configuration results in 89^10 possible seeds
+
+/** Default length of seeds generated by `InstanceOptions` when none is specified. */
 export const SEED_LENGTH = 10;
+/** Default charset used to generate seeds within `InstanceOptions` when none is specified. */
 export const DEFAULT_SEED_CHARSET = EXPANDED_CHARSET;
 
+/**
+ * Generates a psuedo-random seed to use in further psuedo-random data generation.
+ */
 export const generateSeed = () =>
     new Prando().nextString(SEED_LENGTH, DEFAULT_SEED_CHARSET);

src/random/func/recycle-instance-random.ts

@@ -1,7 +1,20 @@
+/**
+ * Contains recycleInstanceRandom function.
+ *
+ * Copyright (c) 2018 Joseph R Cowman
+ * Licensed under MIT License (see https://github.com/regal/regal)
+ */
+
 import { GameInstance } from "../../state";
 import { buildInstanceRandom } from "../impl";
 import { InstanceRandom } from "../instance-random";
 
+/**
+ * Generates a new `InstanceRandom` for the new `GameInstance`, preserving
+ * the old `numGenerations` (as `seed` is preserved by the `GameInstance` itself).
+ * @param oldRandom The `InstanceRandom` of the previous instance.
+ * @param newInstance The new managing `GameInstance`.
+ */
 export const recycleInstanceRandom = (
     oldRandom: InstanceRandom,
     newInstance: GameInstance

src/random/impl/index.ts

@@ -1 +1,9 @@
+/**
+ * The purpose of this file is to abstract all random-related implementations
+ * by re-exporting their constructors from a single file.
+ *
+ * Copyright (c) 2018 Joseph R Cowman
+ * Licensed under MIT License (see https://github.com/regal/regal)
+ */
+
 export { buildInstanceRandom } from "./instance-random-impl";

src/random/impl/instance-random-impl.ts

@@ -1,9 +1,22 @@
+/**
+ * Contains the current implementation of `InstanceRandom`.
+ *
+ * Copyright (c) 2018 Joseph R Cowman
+ * Licensed under MIT License (see https://github.com/regal/regal)
+ */
+
 import Prando from "prando";
 import { RegalError } from "../../error";
 import { GameInstance } from "../../state";
 import { EXPANDED_CHARSET } from "../charsets";
 import { InstanceRandom } from "../instance-random";
 
+/**
+ * Constructs an `InstanceRandom` using the current implementation.
+ * @param game The managing `GameInstance`.
+ * @param numGenerations The number of generations to start from.
+ * Defaults to zero.
+ */
 export const buildInstanceRandom = (
     game: GameInstance,
     numGenerations: number = 0

src/random/instance-random.ts

@@ -1,5 +1,5 @@
 /**
- * Contains the interface to the random component.
+ * Contains the API for the Regal Game Library random component.
  *
  * Copyright (c) 2018 Joseph R Cowman
  * Licensed under MIT License (see https://github.com/regal/regal)
@@ -41,14 +41,20 @@ export interface InstanceRandom {
     decimal(): number;
 
     /**
-     * Generates a string of random characters (duplicate characters allowed).
+     * Generates a string of psudeo- random characters (duplicate characters allowed).
      * @param length The length of the string to generate.
      * @param charset A string containing the characters to choose from when
-     * generating the string. Must be at least two characters long.
+     * generating the string. Duplicates are okay, but the charset must have at
+     * least two unique characters.
      */
     string(length: number, charset?: string);
 
+    /**
+     * Returns a psuedo-random element from the given array without modifying anything.
+     * @param array The array to select from.
+     */
     choice<T>(array: T[]): T;
 
+    /** Generates either `true` or `false` psuedo-randomly. */
     boolean(): boolean;
 }