Docs fixes for proper JSDoc formatting (#131)

Author: anderoonies

entrypoints/chs.js

@@ -1,16 +1,17 @@
 export { default as Console } from '../src/console/index.js';
-export { default as Queue } from '../src/datastructures/queue.js';
-export { default as Stack } from '../src/datastructures/stack.js';
 export { default as Grid } from '../src/datastructures/grid.js';
+export { default as Queue } from '../src/datastructures/queue.js';
 export { default as ExtendedSet } from '../src/datastructures/set.js';
+export { default as Stack } from '../src/datastructures/stack.js';
 export { default as Vector } from '../src/datastructures/vector.js';
 export { default as Arc } from '../src/graphics/arc.js';
 export { default as Circle } from '../src/graphics/circle.js';
 export { default as Color } from '../src/graphics/color.js';
-export { map, getDistance } from '../src/graphics/graphics-utils.js';
+export { getDistance, map } from '../src/graphics/graphics-utils.js';
 export { default as Group } from '../src/graphics/group.js';
+export { default as ImageLibrary } from '../src/graphics/imagelibrary.js';
 export { default as Graphics } from '../src/graphics/index.js';
-export { default as Keyboard } from '../src/graphics/keyboard.js';
+export * as Keyboard from '../src/graphics/keyboard.js';
 export { default as Line } from '../src/graphics/line.js';
 export { default as Oval } from '../src/graphics/oval.js';
 export { default as Polygon } from '../src/graphics/polygon.js';
@@ -19,7 +20,6 @@ export { default as Text } from '../src/graphics/text.js';
 export { default as Thing } from '../src/graphics/thing.js';
 export { default as WebImage } from '../src/graphics/webimage.js';
 export { default as WebVideo } from '../src/graphics/webvideo.js';
-export { default as ImageLibrary } from '../src/graphics/imagelibrary.js';
 export * as Randomizer from '../src/randomizer.js';
 export { default as AudioManager } from '../src/sound/';
 export { default as Audio } from '../src/sound/audio.js';

entrypoints/windowBinder.js

@@ -1,16 +1,17 @@
 import { default as Console } from '../src/console/index.js';
-import { default as Queue } from '../src/datastructures/queue.js';
-import { default as Stack } from '../src/datastructures/stack.js';
 import { default as Grid } from '../src/datastructures/grid.js';
+import { default as Queue } from '../src/datastructures/queue.js';
 import { default as ExtendedSet } from '../src/datastructures/set.js';
+import { default as Stack } from '../src/datastructures/stack.js';
 import { default as Vector } from '../src/datastructures/vector.js';
 import { default as Arc } from '../src/graphics/arc.js';
 import { default as Circle } from '../src/graphics/circle.js';
 import { default as Color } from '../src/graphics/color.js';
-import { map, getDistance } from '../src/graphics/graphics-utils.js';
+import { getDistance, map } from '../src/graphics/graphics-utils.js';
 import { default as Group } from '../src/graphics/group.js';
+import { default as ImageLibrary } from '../src/graphics/imagelibrary.js';
 import { default as GraphicsManager } from '../src/graphics/index.js';
-import { default as Keyboard } from '../src/graphics/keyboard.js';
+import * as Keyboard from '../src/graphics/keyboard.js';
 import { default as Line } from '../src/graphics/line.js';
 import { default as Oval } from '../src/graphics/oval.js';
 import { default as Polygon } from '../src/graphics/polygon.js';
@@ -19,7 +20,6 @@ import { default as Text } from '../src/graphics/text.js';
 import { default as Thing } from '../src/graphics/thing.js';
 import { default as WebImage } from '../src/graphics/webimage.js';
 import { default as WebVideo } from '../src/graphics/webvideo.js';
-import { default as ImageLibrary } from '../src/graphics/imagelibrary.js';
 import * as Randomizer from '../src/randomizer.js';
 import { default as Audio } from '../src/sound/audio.js';
 import { default as AudioManager } from '../src/sound/index.js';
@@ -60,6 +60,7 @@ window.mouseDownMethod = GraphicsInstance.mouseDownMethod.bind(GraphicsInstance)
 window.mouseDragMethod = GraphicsInstance.mouseDragMethod.bind(GraphicsInstance);
 window.mouseUpMethod = GraphicsInstance.mouseUpMethod.bind(GraphicsInstance);
 window.mouseMoveMethod = GraphicsInstance.mouseMoveMethod.bind(GraphicsInstance);
+window.waitForClick = GraphicsInstance.waitForClick.bind(GraphicsInstance);
 window.stopAllTimers = GraphicsInstance.stopAllTimers.bind(GraphicsInstance);
 window.setMainTimer = GraphicsInstance.setMainTimer.bind(GraphicsInstance);
 window.stopTimer = GraphicsInstance.stopTimer.bind(GraphicsInstance);

package.json

@@ -19,7 +19,7 @@
         "build": "node build.js",
         "dev": "node build.js watch",
         "dist": "tsc && node build.js dist",
-        "docs": "npm run build && cp -r dist/* ./site/assets/ && jsdoc src/**/*.js --template node_modules/docdash --destination _site/docs",
+        "docs": "npm run build && cp -r dist/* ./site/assets/ && jsdoc --readme src/DOCSREADME.md src/**/*.js src/*.js --template node_modules/docdash --destination _site/docs",
         "prepare": "husky install",
         "site": "npm run docs && npx @11ty/eleventy",
         "site:watch": "npm run docs && npx @11ty/eleventy --watch"

src/DOCSREADME.md

@@ -0,0 +1,44 @@
+# CodeHS JavaScript Library
+
+Welcome! This is documentation for the CodeHS JavaScript Library.
+
+## Graphics
+
+-   [Color]{@link module:Color~Color}
+-   [Keyboard]{@link module:Keyboard}
+
+### Shapes
+
+-   {@link Arc}
+-   {@link Circle}
+-   {@link Group}
+-   {@link Line}
+-   {@link Oval}
+-   {@link Polygon}
+-   {@link Rectangle}
+-   {@link Text}
+-   {@link Thing}
+-   {@link WebImage}
+-   {@link WebVideo}
+
+## Console
+
+-   {@link readInt}
+-   {@link readLine}
+-   {@link readFloat}
+-   {@link readBoolean}
+-   {@link print}
+-   {@link println}
+
+## Data Structures
+
+-   {@link Grid}
+-   {@link Queue}
+-   {@link ExtendedSet}
+-   {@link Stack}
+-   {@link Vector}
+
+## Audio
+
+-   {@link Audio}
+-   {@link Sound}

src/console/index.js

@@ -1,16 +1,36 @@
-/* Console
- *
- * A console represents a text console that allows the user to print, println,
- * and read an integer using readInt, and read a float using readFloat. These
- * functions pop up prompt dialogs and make sure that the results are actually
- * of the desired type.
- *
- * @author  Jeremy Keeshin    July 9, 2012
- * @author  Andy Bayer        Fall 2021
+/**
+ * Console provides utilities for interacting with a text console.
+ * {@link Console#readInt}, {@link Console#readFloat}, {@link Console#readBoolean}, and {@link Console#readLine}
+ * prompt the user for input and parse it to the corresponding type. This prompt will use the blocking
+ * browser prompt by default, but can be configured using {@link Console#onPrompt}.
  *
+ * Console also exposes {@link Console#print} and {@link Console#println}, which are used for
+ * emitting output. By default the output will print to the console, but can be configured using
+ * {@link Console#onPrint}.
  */
+class Console {
+    /**
+     * Function invoked when asking for user input.
+     * This function is invoked with the string of the prompt, i.e. readInt('give me an int!').
+     * The result of invoking onPrompt will be subjected to parsing functions for confirming
+     * it's an appropriate data type (a float, in the case of readFloat, for example). If
+     * onPrompt is undefined, window.prompt is used as a fallback.
+     * @type {function}
+     */
+    onPrompt = window.prompt.bind(window);
+    /**
+     * Function invoked when printing.
+     * This function is invoked with any output, either in the case of explicit calls to `print`
+     * or `println` or internal calls within the library. If onPrint is undefined, console.log
+     * is used as a fallback.
+     * @type {function}
+     */
+    onPrint = window.console.log.bind(window.console);
+    /**
+     * Function invoked when {@link Console#clear} is called.
+     */
+    onClear = window.console.clear.bind(window.console);
 
-export default class Console {
     /**
      * Initialize the console class, additionally configuring any event handlers.
      * @constructor
@@ -28,7 +48,7 @@ export default class Console {
     constructor(options = {}) {
         this.onPrompt = options.onPrompt ?? window.prompt.bind(window);
         this.onPrint = options.onPrint ?? window.console.log.bind(window.console);
-        this.onClear = options.onClear ?? (() => {});
+        this.onClear = options.onClear ?? window.console.clear.bind(window.console);
     }
 
     /**
@@ -63,6 +83,7 @@ export default class Console {
 
     /**
      * Clear the console.
+     * @global
      */
     clear() {
         this.onClear();
@@ -71,6 +92,7 @@ export default class Console {
     /**
      * Print a value to the console.
      * @param {...any} args - Anything to print.
+     * @global
      */
     print(...args) {
         if (args.length < 1) {
@@ -82,6 +104,7 @@ export default class Console {
     /**
      * Print a value to the console, followed by a newline character.
      * @param {any} value - The value to print.
+     * @global
      */
     println(value) {
         if (arguments.length === 0) {
@@ -112,6 +135,7 @@ export default class Console {
      * why a given input was rejected. For example, the errorMsgType "an integer," would result in
      * printing "That was not an integer. Please try again." if parseFn failed.
      * @returns {number}
+     * @global
      */
     readNumber(str, parseFn, errorMsgType) {
         const DEFAULT = 0; // If we get into an infinite loop, return DEFAULT.
@@ -120,10 +144,10 @@ export default class Console {
         let promptString = str;
         let loopCount = 0;
         /**
-         * @type {boolean}
          * indicates whether the parsing has been successful, meaning
          * it hasn't hit the INFINITE_LOOP_CHECK or null cases, and the input from the user has
          * satisfied parseFn. in this case, the input should be printed.
+         * @type {boolean}
          * */
         let successful = false;
         let parsedResult;
@@ -163,6 +187,7 @@ export default class Console {
      * Read a line from the user.
      * @param {str} str - A message associated with the modal asking for input.
      * @returns {str} The result of the readLine prompt.
+     * @global
      */
     readLine(str) {
         if (arguments.length !== 1) {
@@ -179,6 +204,7 @@ export default class Console {
      * Read a bool from the user.
      * @param {str} str - A message associated with the modal asking for input.
      * @returns {str} The result of the readBoolean prompt.
+     * @global
      */
     readBoolean(str) {
         if (arguments.length !== 1) {
@@ -208,6 +234,7 @@ export default class Console {
      * though they are successfully parsed as ints.
      * @param {str} str - A message associated with the modal asking for input.
      * @returns {str} The result of the readInt prompt.
+     * @global
      */
     readInt(str) {
         if (arguments.length !== 1) {
@@ -233,6 +260,7 @@ export default class Console {
      * Read a float with our safe helper function.
      * @param {str} str - A message associated with the modal asking for input.
      * @returns {str} The result of the readFloat prompt.
+     * @global
      */
     readFloat(str) {
         if (arguments.length !== 1) {
@@ -242,3 +270,5 @@ export default class Console {
         return this.readNumber(str, parseFloat, 'a float');
     }
 }
+
+export default Console;

src/datastructures/grid.js

@@ -1,13 +1,13 @@
-/** @module Grid */
-
 /**
  * A grid is an abstraction around a two-dimensional array.
+ * @class
  */
 class Grid {
     type = 'Grid';
 
     /**
      * Constructs a grid.
+     * @constructor
      * @param {number} rows
      * @param {number} cols
      */

src/datastructures/queue.js

@@ -1,6 +1,9 @@
-'use strict';
-
-export default class Queue extends Array {
+/**
+ * A Queue is an Array subclass that implements First In, First Out ordering
+ * @class
+ * @extends Array
+ */
+class Queue extends Array {
     /**
      * Get the number of objects in the queue.
      * @returns {number} Number of elements in the queue.
@@ -52,3 +55,5 @@ export default class Queue extends Array {
         return this.length === 0;
     }
 }
+
+export default Queue;

src/datastructures/set.js

@@ -1,3 +1,8 @@
+/**
+ * The ExtendedSet extends the native Set implementation, adding some functionality.
+ * @class
+ * @extends Set
+ */
 class ExtendedSet extends Set {
     /**
      * Returns whether the set is empty.

src/datastructures/stack.js

@@ -1,4 +1,9 @@
-export default class Stack extends Array {
+/**
+ * A Stack is a subclass of an Array that implements First In, Last Out ordering.
+ * @class
+ * @extends Array
+ */
+class Stack extends Array {
     /**
      * Get the number of objects in the stack.
      * @returns {number} Number of elements in the stack.
@@ -38,3 +43,5 @@ export default class Stack extends Array {
         return this.length === 0;
     }
 }
+
+export default Stack;

src/datastructures/vector.js

@@ -1,5 +1,9 @@
 import { degreesToRadians, radiansToDegrees } from '../graphics/arc.js';
 
+/**
+ * The Vector class is ued to model a 2 or 3 dimensional vector.
+ * @class
+ */
 class Vector {
     /**
      * @constructor
@@ -27,13 +31,10 @@ class Vector {
 
     /**
      * Add a vector to this one, modifying this one.
-     * @method add
-     * @param {number} x   the x component of the vector to be added
+     * @param {number|Vector|number[]} x   the x component of the vector to be added.
+     *  Alternatively, a Vector or list of numbers to add.
      * @param {number} [y] the y component of the vector to be added
      * @param {number} [z] the z component of the vector to be added
-     *
-     * @method add
-     * @param {Vector|number[]} vector vector or array to add
      * @returns {Vector} this vector, modified
      */
     add(x, y, z) {
@@ -57,13 +58,11 @@ class Vector {
 
     /**
      * Subtract a vector from this one, modifying this one.
-     * @method subtract
-     * @param {number} x   the x component of the vector to be subtracted
+     * @param {number|Vector|number[]} x   the x component of the vector to be subtracted
+     *  Alternatively, a Vector or list of numbers to substract.
      * @param {number} [y] the y component of the vector to be subtracted
      * @param {number} [z] the z component of the vector to be subtracted
      *
-     * @method subtract
-     * @param {Vector|number[]} vector vector or array to subtract
      * @returns {Vector} this vector, modified
      */
     subtract(x, y, z) {
@@ -87,13 +86,12 @@ class Vector {
 
     /**
      * Multiply this vector by a vector, scalar, or array, modifying it in place and returning it.
-     * @method multiply
-     * @param {number} x   scalar to multiply the x component by
+     * @param {number|Vector|number[]} x   scalar to multiply the x component by
+     *  Alternatively, a Vector or list of numbers to multiply
      * @param {number} [y] scalar to multiply the y component by
      * @param {number} [z] scalar to multiply the z component by
      *
-     * @method add
-     * @param {Vector|number[]} vector vector or array to multiply
+     k
      * @returns {Vector} this vector, modified
      */
     multiply(x, y, z) {