docs: add attribution for adapted code

Adds links for XORShift32, Mulberry32 and LCG PRNG implementations, which are in the public domain. Adds a link for the sinFract() function, which is adapted from The Art of Code's YouTube video on Value Noise. Adds MIT license text and link for Quadtree class, which is adapted from CodingTrain/QuadTree. Refs: #72, #73
jakebeamish · Sep 6, 2024 · bd18f10 · bd18f10
1 parent 6714cf9
commit bd18f10
Show file tree

Hide file tree

Showing 4 changed files with 103 additions and 15 deletions.
diff --git a/LICENSE.md b/LICENSE.md
@@ -1,7 +1,33 @@
+## jakebeamish/Penplotting.js
+
 The MIT License (MIT) Copyright (c) 2024 Jake Beamish
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 
 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+## CodingTrain/QuadTree
+
+MIT License
+
+Copyright (c) 2021 Coding Train
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/source/Quadtree.js b/source/Quadtree.js
@@ -1,5 +1,12 @@
 import { Rectangle } from "./Rectangle.js";
-/** Class representing a quadtree. */
+/**
+ * Class representing a quadtree.
+ * 
+ * This implementation is adapted from CodingTrain/QuadTree, which is released
+ * with an MIT License. For the full license text, see `/LICENCE.md#CodingTrain/QuadTree`.
+ *
+ * @see https://github.com/CodingTrain/QuadTree
+ */
 export class Quadtree {
     /**
      * Create a quadtree.
@@ -117,4 +124,4 @@ export class Quadtree {
             this.bottomRight.show(sketch);
         }
     }
-}
+}
diff --git a/source/Random.js b/source/Random.js
@@ -109,13 +109,24 @@ export class PRNG {
 }
 
 /**
- * @summary Linear Congruential Generator (LCG) implemenation of PRNG.
+ * LCG (Linear Congruential Generator) Pseudorandom Number Generator Class
  * @extends PRNG
+ * 
+ * @summary Implements the LCG algorithm to generate pseudorandom numbers.
+ * @description
+ * This class provides the LCG method of generating psuedorandom
+ * numbers to the {@link PRNG} class.
+ * 
+ * @example
+ * const rng = new LCG(123456789);
+ * console.log(rng.next()); // Generates a pseudorandom number
+ * 
+ * @see https://en.wikipedia.org/wiki/Linear_congruential_generator
  */
 export class LCG extends PRNG {
     /**
      * Creates an instance of LCG.
-     * @param {number} seed - The seed number.
+     * @param {number} seed - The seed value for the LCG PRNG.
      */
     constructor(seed) {
         super(seed);
@@ -126,8 +137,8 @@ export class LCG extends PRNG {
     }
 
     /**
-     * Generates the next psuedo-random number.
-     * @returns {number} - The next psuedo-random number.
+     * Generates the next pseudorandom number.
+     * @returns {number} A pseudorandom number in the range [0-1).
      */
     next() {
         this.state = (this.multiplier * this.state + this.increment) % this.modulus;
@@ -136,16 +147,30 @@ export class LCG extends PRNG {
 
     /**
      * Returns the maximum possible value of the LCG.
-     * @returns {number} - The maximum value (2^32).
+     * @returns {number} The maximum value (2^32).
      */
     maxValue() {
         return this.modulus;
     }
 }
 
 /**
- * @summary Mulberry32 implementation of PRNG.
+ * Mulberry32 Pseudorandom Number Generator Class
  * @extends PRNG
+ * 
+ * @summary Implements the Mulberry32 algorithm to generate pseudorandom numbers.
+ * @description
+ * This class provides the Mulberry32 method of generating psuedorandom
+ * numbers to the {@link PRNG} class.
+ * 
+ * The Mulberry32 algorithm was written by Tommy Ettinger in 2017 and is released to the public domain, meaning it can be freely used, modified, and distributed without restrictions.
+ * 
+ * @example
+ * const rng = new Mulberry32(123456789);
+ * console.log(rng.next()); // Generates a pseudorandom number
+ * 
+ * @see https://gist.github.com/tommyettinger/46a874533244883189143505d203312c
+
  */
 export class Mulberry32 extends PRNG {
     /**
@@ -159,15 +184,20 @@ export class Mulberry32 extends PRNG {
 
     /**
      * Returns the maximum possible value of Mulberry32.
-     * @returns {number} - The maximum value (2^32).
+     * @returns {number} The maximum value (2^32).
      */
     maxValue() {
         return 2 ** 32;
     }
 
     /**
      * Generates the next psuedo-random number.
-     * @returns {number} - The next psuedo-random number.
+     * @returns {number} A number in the range [0-1).
+     * 
+     * @example
+     * // Returns a random number in the range [0-1)
+     * const rng = new Mulberry32();
+     * console.log(rng.next());
      */
     next() {
         let t = this.state += 0x6D2B79F5;
@@ -179,8 +209,24 @@ export class Mulberry32 extends PRNG {
 }
 
 /**
- * @summary XORShift32 implementation of PRNG.
+ * XORShift32 Pseudorandom Number Generator Class
  * @extends PRNG
+ * 
+ * @summary Implements the XORShift32 algorithm to generate pseudorandom numbers.
+ * @description
+ * This class provides the XORShift32 method of generating psuedorandom
+ * numbers to the {@link PRNG} class. It uses bitwise operations
+ * to generate a sequence of pseudorandom 32-bit unsigned integers.
+ * 
+ * The XORShift algorithm was written by Geogrge Marsaglia in 2003 and is released to the public domain, meaning it can be freely used, modified, and distributed without restrictions.
+ * 
+ * @example
+ * const rng = new XORShift32(123456789);
+ * console.log(rng.next()); // Generates a pseudorandom number
+ * 
+ * @see Marsaglia, G. (2003) "XORShift RNGs", Journal of Statistical Software
+ *      https://www.jstatsoft.org/article/view/v008i14
+
  */
 export class XORShift32 extends PRNG {
     constructor(seed) {
@@ -190,15 +236,20 @@ export class XORShift32 extends PRNG {
 
     /**
    * Returns the maximum possible value of XORShift32.
-   * @returns {number} - The maximum value (2^32).
+   * @returns {number} The maximum value (2^32).
    */
     maxValue() {
         return 2 ** 32;
     }
 
     /**
      * Generates the next psuedo-random number.
-     * @returns {number} - The next psuedo-random number.
+     * @returns {number} A number in the range [0-1).
+     * 
+     * @example
+     * // Returns a random number in the range [0-1)
+     * const rng = new XORShift32();
+     * console.log(rng.next());
      */
     next() {
         let a = this.state;

diff --git a/source/utils.js b/source/utils.js
@@ -1,5 +1,9 @@
 /**
- * Generate pseudo-random numbers from `x` and `y` co-ordinates
+ * Generates pseudo-random numbers from `x` and `y` co-ordinates. This
+ * technique is adapted from The Art of Code's YouTube video on value noise.
+ *
+ * @see https://www.youtube.com/watch?v=zXsWftRdsvU
+ * 
  * @returns {number} - A floating point number between 0 and 1
  */
 export function sinFract(x, y, a, b, m) {
@@ -79,4 +83,4 @@ export function hexToDec(hex) {
  */
 export function decToHex(dec, length = 8) {
 	return dec.toString(16).padStart(length, "0");
-}
+}