Adding documentation to builder helpers

src/builders/Builder.ts

@@ -1,31 +1,93 @@
 import Module from '@app/module/Module';
 import NoiseMap from '@app/noisemap';
 
+/**
+ * Abstract base class for a noise-map builder
+ *
+ * A builder class builds a noise map by filling it with coherent-noise
+ * values generated from the surface of a three-dimensional mathematical
+ * object.  Each builder class defines a specific three-dimensional
+ * surface, such as a cylinder, sphere, or plane.
+ *
+ * A builder class describes these input values using a coordinate system
+ * applicable for the mathematical object (e.g., a latitude/longitude
+ * coordinate system for the spherical noise-map builder.)  It then
+ * "flattens" these coordinates onto a plane so that it can write the
+ * coherent-noise values into a two-dimensional noise map.
+ */
 export default abstract class Builder {
+  /**
+   * The source module.
+   *
+   * This object fills in a noise map with the coherent-noise values
+   * from this source module.
+   *
+   * The source module must exist throughout the lifetime of this
+   * object unless another noise module replaces that noise module.
+   */
   public sourceModule: Module;
+  /**
+   * The destination noise map.
+   *
+   * The destination noise map will contain the coherent-noise values
+   * from this noise map after a successful call to the Build() method.
+   *
+   * The destination noise map must exist throughout the lifetime of
+   * this object unless another noise map replaces that noise map.
+   */
   public noiseMap: NoiseMap;
 
+  /**
+   * @param sourceModule The source module
+   * @param width The width of the destination noise map, in points
+   * @param height The height of the destination noise map, in points
+   */
   public constructor(sourceModule: Module, width: number, height: number) {
     this.sourceModule = sourceModule;
     this.noiseMap = new NoiseMap(width, height);
   }
 
   // Functions
+  /**
+   * Builds the noise map.
+   * @returns Updated instance of noise map
+   */
   public abstract build(): NoiseMap;
 
+  /**
+   * Sets the size of the destination noise map.
+   *
+   * @param width The width of the destination noise map, in points.
+   * @param height The height of the destination noise map, in points.
+   *
+   * This method does not change the size of the destination noise map
+   * until the Build() method is called.
+   */
   public setSize(width: number, height: number): void {
     this.width = width;
     this.height = height;
   }
 
   // Properties
+  /**
+   * The width of the destination noise map, in points.
+   *
+   * This object does not change the width in the destination noise
+   * map object until the build() method is called.
+   */
   public get width(): number {
     return this.noiseMap.width;
   }
   public set width(width: number) {
     this.noiseMap.width = width;
   }
 
+  /**
+   * The height of the destination noise map, in points.
+   *
+   * This object does not change the height in the destination noise
+   * map object until the build() method is called.
+   */
   public get height(): number {
     return this.noiseMap.height;
   }

src/builders/cylinder.ts

@@ -2,12 +2,40 @@ import Cylinder from '@app/model/cylinder';
 import NoiseMap from '@app/noisemap';
 import Builder from './Builder';
 
+/**
+ * Builds a cylindrical noise map.
+ *
+ * This class builds a noise map by filling it with coherent-noise values
+ * generated from the surface of a cylinder.
+ *
+ * This class describes these input values using an (angle, height)
+ * coordinate system.  After generating the coherent-noise value from the
+ * input value, it then "flattens" these coordinates onto a plane so that
+ * it can write the values into a two-dimensional noise map.
+ *
+ * The cylinder model has a radius of 1.0 unit and has infinite height.
+ * The cylinder is oriented along the y axis.  Its center is at the
+ * origin.
+ *
+ * The x coordinate in the noise map represents the angle around the
+ * cylinder's y axis.  The y coordinate in the noise map represents the
+ * height above the x-z plane.
+ *
+ * The application must provide the lower and upper angle bounds of the
+ * noise map, in degrees, and the lower and upper height bounds of the
+ * noise map, in units.
+ */
 class NoiseMapBuilderCylinder extends Builder {
   private _lowerAngleBound: number = 0;
   private _lowerHeightBound: number = 0;
   private _upperAngleBound: number = 1;
   private _upperHeightBound: number = 1;
 
+  /**
+   * Lower angle boundary of the cylindrical noise map, in degrees.
+   *
+   * The lower angle boundary must be less than the upper angle boundary.
+   */
   public get lowerAngleBound(): number {
     return this._lowerAngleBound;
   }
@@ -19,6 +47,12 @@ class NoiseMapBuilderCylinder extends Builder {
     this._lowerAngleBound = v;
   }
 
+  /**
+   * Lower height boundary of the cylindrical noise map, in units.
+   * One unit is equal to the radius of the cylinder.
+   *
+   * The lower height boundary must be less than the upper height boundary.
+   */
   public get lowerHeightBound(): number {
     return this._lowerHeightBound;
   }
@@ -30,6 +64,11 @@ class NoiseMapBuilderCylinder extends Builder {
     this._lowerHeightBound = v;
   }
 
+  /**
+   * Upper angle boundary of the cylindrical noise map, in degrees.
+   *
+   * The upper angle boundary must be greater than the lower angle boundary.
+   */
   public get upperAngleBound(): number {
     return this._upperAngleBound;
   }
@@ -41,6 +80,12 @@ class NoiseMapBuilderCylinder extends Builder {
     this._upperAngleBound = v;
   }
 
+  /**
+   * Upper height boundary of the cylindrical noise map, in units.
+   * One unit is equal to the radius of the cylinder.
+   *
+   * The upper height boundary must be greater than the lower height boundary.
+   */
   public get upperHeightBound(): number {
     return this._upperHeightBound;
   }
@@ -75,10 +120,20 @@ class NoiseMapBuilderCylinder extends Builder {
     return this.noiseMap;
   }
 
-  public setBounds(lowerAngleBound: number, lowerHeightBound: number, upperAngleBound: number, upperHeightBound: number): void {
+  /**
+   * Sets the coordinate boundaries of the noise map.
+   *
+   * @param lowerAngleBound The lower angle boundary of the noise map, in degrees.
+   * @param upperAngleBound The upper angle boundary of the noise map, in degrees.
+   * @param lowerHeightBound The lower height boundary of the noise map, in units.
+   * @param upperHeightBound The upper height boundary of the noise map, in units.
+   *
+   * One unit is equal to the radius of the cylinder.
+   */
+  public setBounds(lowerAngleBound: number, upperAngleBound: number, lowerHeightBound: number, upperHeightBound: number): void {
     this.lowerAngleBound = lowerAngleBound;
-    this.lowerHeightBound = lowerHeightBound;
     this.upperAngleBound = upperAngleBound;
+    this.lowerHeightBound = lowerHeightBound;
     this.upperHeightBound = upperHeightBound;
   }
 }

src/builders/plane.ts

@@ -4,19 +4,52 @@ import Module from '@app/module/Module';
 import NoiseMap from '@app/noisemap';
 import Builder from './Builder';
 
+/**
+ * Builds a planar noise map.
+ *
+ * This class builds a noise map by filling it with coherent-noise values
+ * generated from the surface of a plane.
+ *
+ * This class describes these input values using (x, y) coordinates.
+ * Their z coordinates are always 0.0.
+ *
+ * The application must provide the lower and upper x coordinate bounds
+ * of the noise map, in units, and the lower and upper y coordinate
+ * bounds of the noise map, in units.
+ *
+ * To make a tileable noise map with no seams at the edges, set `seamless` to true.
+ */
+// @TODO refactor y coordinates into z coordinates
 class NoiseMapBuilderPlane extends Builder {
-  private seamless: boolean;
+  /**
+   * A flag that enables or disables seamless tiling.
+   *
+   * Enabling seamless tiling builds a noise map with no seams at the
+   * edges.  This allows the noise map to be tileable.
+   */
+  public seamless: boolean;
   private _lowerXBound: number = 0;
   private _lowerYBound: number = 0;
   private _upperXBound: number = 1;
   private _upperYBound: number = 1;
 
+  /**
+   * @param sourceModule The source module
+   * @param width The width of the destination noise map, in points
+   * @param height The height of the destination noise map, in points
+   * @param seamless A flag that enables or disables seamless tiling
+   */
   constructor(sourceModule: Module, width: number = 256, height: number = 256, seamless: boolean = false) {
     super(sourceModule, width, height);
 
     this.seamless = seamless;
   }
 
+  /**
+   * The lower x boundary of the noise map, in units.
+   *
+   * The lower x boundary must be less than the upper x boundary.
+   */
   public get lowerXBound(): number {
     return this._lowerXBound;
   }
@@ -28,6 +61,11 @@ class NoiseMapBuilderPlane extends Builder {
     this._lowerXBound = v;
   }
 
+  /**
+   * The lower y boundary of the noise map, in units.
+   *
+   * The lower y boundary must be less than the upper y boundary.
+   */
   public get lowerYBound(): number {
     return this._lowerYBound;
   }
@@ -39,6 +77,11 @@ class NoiseMapBuilderPlane extends Builder {
     this._lowerYBound = v;
   }
 
+  /**
+   * The upper x boundary of the noise map, in units.
+   *
+   * The upper x boundary must be greater than the lower x boundary.
+   */
   public get upperXBound(): number {
     return this._upperXBound;
   }
@@ -50,6 +93,11 @@ class NoiseMapBuilderPlane extends Builder {
     this._upperXBound = v;
   }
 
+  /**
+   * The upper y boundary of the noise map, in units.
+   *
+   * The upper y boundary must be greater than the lower y boundary.
+   */
   public get upperYBound(): number {
     return this._upperYBound;
   }
@@ -115,6 +163,14 @@ class NoiseMapBuilderPlane extends Builder {
     return this.noiseMap;
   }
 
+  /**
+   * Sets the boundaries of the planar noise map.
+   *
+   * @param lowerXBound The lower x boundary of the noise map, in units.
+   * @param lowerYBound The lower y boundary of the noise map, in units.
+   * @param upperXBound The upper x boundary of the noise map, in units.
+   * @param upperYBound The upper y boundary of the noise map, in units.
+   */
   public setBounds(lowerXBound: number, lowerYBound: number, upperXBound: number, upperYBound: number): void {
     this.upperXBound = upperXBound;
     this.upperYBound = upperYBound;