Merge pull request #294 from uiuc-ischool-accessible-computing-lab/do…

…cumentation

Documentation

CHANGELOG.md

@@ -11,5 +11,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added some notes on manual testing
 - Fixed typo in task1_bar_plot.html, correct CSS file now called
 - Fixed initial position out of range, #287
+- Updated documentation for all scripts
 
 ## [1.0.0] - 2023-11-01

src/js/audio.js

@@ -33,9 +33,9 @@ class Audio {
     return compressor;
   }
 
-  // an oscillator is created and destroyed after some falloff
   /**
-   * Plays a tone based on the current chart type and position.
+   * Initilizes a tone play based on the current chart type and position.
+   * Triggers playOscillator() with the correct parameters.
    */
   playTone(params = null) {
     let currentDuration = constants.duration;
@@ -336,6 +336,7 @@ class Audio {
 
   /**
    * Plays an oscillator with the given frequency, duration, panning, volume, and wave type.
+   * Typically used by playTone(), which does all the heavy lifting.
    * @param {number} frequency - The frequency of the oscillator.
    * @param {number} currentDuration - The duration of the oscillator in seconds.
    * @param {number} panning - The panning value of the oscillator.
@@ -411,6 +412,7 @@ class Audio {
 
   /**
    * Plays a smooth sound with the given frequency array, duration, panning array, volume, and wave type.
+   * The idea here is you give it an array of frequencies, and it plays them smoothly in order, like listening to a whole line chart
    * @param {number[]} freqArr - The array of frequencies to play.
    * @param {number} currentDuration - The duration of the sound in seconds.
    * @param {number[]} panningArr - The array of panning values.
@@ -478,7 +480,8 @@ class Audio {
   }
 
   /**
-   * Plays a null frequency sound.
+   * Initializes play of a custom null frequency sound.
+   * Calls the usual playOscillator() to do so.
    */
   PlayNull() {
     let frequency = constants.NULL_FREQUENCY;
@@ -570,7 +573,6 @@ class Audio {
    * @returns {number} The new value between min and max.
    */
   SlideBetween(val, a, b, min, max) {
-    // helper function that goes between min and max proportional to how val goes between a and b
     let newVal = ((val - a) / (b - a)) * (max - min) + min;
     if (a == 0 && b == 0) {
       newVal = 0;

src/js/boxplot.js

@@ -1,8 +1,3 @@
-//
-// BoxPlot class.
-// This initializes and contains the JSON data model for this chart
-//
-// todo:
 /**
  * A class representing a box plot.
  * @class
@@ -14,6 +9,8 @@ class BoxPlot {
    */
   constructor() {
     constants.plotOrientation = 'horz'; // default
+
+    // the default sections for all boxplots
     this.sections = [
       'lower_outlier',
       'min',
@@ -117,8 +114,6 @@ class BoxPlot {
    * Cleans up data and extra variables like min/max stuff.
    */
   CleanData() {
-    // clean up data and extra vars like min / max stuff
-
     let min, max;
     for (let i = 0; i < this.plotData.length; i++) {
       if (this.plotData[i].lower_outlier) {
@@ -467,15 +462,10 @@ class BoxPlot {
    * @returns {string[]} Array of segment types.
    */
   GetAllSegmentTypes() {
-    let allWeNeed = [
-      resources.GetString('lower_outlier'),
-      resources.GetString('min'),
-      resources.GetString('25'),
-      resources.GetString('50'),
-      resources.GetString('75'),
-      resources.GetString('max'),
-      resources.GetString('upper_outlier'),
-    ];
+    let allWeNeed = [];
+    for (let i = 0; i < this.sections.length; i++) {
+      allWeNeed.push(resources.GetString(this.sections[i]));
+    }
 
     return allWeNeed;
   }
@@ -644,7 +634,6 @@ class BoxPlot {
  * @class
  */
 class BoxplotRect {
-  // maybe put this stuff in user config?
   /**
    * The padding between rectangles in pixels.
    * @type {number}
@@ -673,8 +662,6 @@ class BoxplotRect {
    * Updates the bounding box values from the object and gets bounds of visual outline to be drawn.
    */
   UpdateRect() {
-    // UpdateRect takes bounding box values from the object and gets bounds of visual outline to be drawn
-
     if (document.getElementById('highlight_rect'))
       document.getElementById('highlight_rect').remove(); // destroy to be recreated
 

src/js/constants.js

@@ -1,13 +1,9 @@
 /**
- * A class representing constants used throughout the application.
+ * A class representing system vars, user config vars, and helper functions used throughout the application.
+ *
  * @class
  */
 class Constants {
-  // element ids
-  /**
-   * The ID of the chart container element.
-   * @type {string}
-   */
   chart_container_id = 'chart-container';
   main_container_id = 'maidr-container';
   //chart_container_class = 'chart-container'; // remove later
@@ -26,11 +22,6 @@ class Constants {
   events = [];
   postLoadEvents = [];
 
-  // default constructor for all charts
-  /**
-   * Creates a new instance of the Constants class.
-   * @constructor
-   */
   constructor() {}
 
   // BTS modes initial values

src/js/display.js

@@ -49,7 +49,7 @@ class Display {
 
   /**
    * Toggles braille mode on or off.
-   * @param {string} [onoff] - Optional parameter to explicitly set braille mode on or off.
+   * @param {string} [onoff] - Optional parameter to explicitly set braille mode on or off. If not supplied, defaults to toggling the current braille mode.
    * @returns {void}
    */
   toggleBrailleMode(onoff) {
@@ -168,6 +168,7 @@ class Display {
 
   /**
    * Changes the chart layer up or down and updates the position relative to where we were on the previous layer.
+   * This only applies to charts that have multiple layers, such as point and smooth in a standard scatterplot.
    * @param {string} [updown='down'] - The direction to change the chart layer. Can be 'up' or 'down'. Defaults to 'down'.
    */
   changeChartLayer(updown = 'down') {
@@ -279,6 +280,7 @@ class Display {
 
   /**
    * Builds an html text string to output to both visual users and aria live based on what chart we're on, our position, and the mode.
+   * Typical output is something like "x is 5, y is 10".
    * @function
    * @memberof module:display
    * @returns {void}
@@ -607,7 +609,7 @@ class Display {
   }
 
   /**
-   * Displays information on the webpage based on the textType and textValue provided.
+   * Displays information on the webpage and an aria live region based on the textType and textValue provided.
    * @param {string} textType - The type of text to be displayed.
    * @param {string} textValue - The value of the text to be displayed.
    */
@@ -1081,6 +1083,7 @@ class Display {
 
   /**
    * Calculates the impact of character length on the given character data.
+   * Used by boxplots.
    * @param {Object} charData - The character data to calculate the impact for.
    * @param {number} charData.length - The total length of all characters.
    * @param {number} charData.numChars - The total number of characters.

src/js/histogram.js

@@ -1,11 +1,3 @@
-/**
- * A class representing a histogram.
- * @class
- */
-/**
- * A class representing a histogram.
- * @class
- */
 /**
  * A class representing a histogram.
  * @class

src/js/init.js

@@ -73,11 +73,11 @@ document.addEventListener('DOMContentLoaded', function (e) {
 });
 
 /**
- * Initializes the Maidr chart with the given configuration.
- * @param {Object} thisMaidr - The configuration object for the Maidr chart.
+ * Initializes the Maidr app for a given chart, taken from the matching ID of the focused chart
+ * @param {Object} thisMaidr - The json schema for the chart to be initialized.
  */
 function InitMaidr(thisMaidr) {
-  // just in case
+  // there's a rare bug where constants isn't defined yet, so we check for that
   if (typeof constants != 'undefined') {
     // init vars and html
     window.singleMaidr = thisMaidr;
@@ -88,7 +88,7 @@ function InitMaidr(thisMaidr) {
       constants.chartType = singleMaidr.type;
     }
     CreateChartComponents(singleMaidr);
-    window.control = new Control(); // this inits the plot
+    window.control = new Control(); // this inits the actual chart object and Position
     window.review = new Review();
     window.display = new Display();
     window.audio = new Audio();
@@ -106,6 +106,7 @@ function InitMaidr(thisMaidr) {
     // kill autoplay event
     constants.events.push([document, 'keydown', KillAutoplayEvent]);
 
+    // actually do eventlisteners for all events
     this.SetEvents();
 
     // once everything is set up, announce the chart name (or title as a backup) to the user
@@ -118,15 +119,14 @@ function InitMaidr(thisMaidr) {
 }
 
 /**
- * Determines whether to initialize Maidr based on certain conditions.
+ * Determines whether to initialize Maidr based on conditions:
+  - maidr isn't enabled (check if singleMaidr is undefined or false)
+  - the chart we're moving to isn't the same as the one we're on
+  If successful, calls InitMaidr. If not, does nothing.
+  note: if we move from one to another, destroy the current first
  * @param {Object} thisMaidr - The Maidr object to be initialized.
  */
 function ShouldWeInitMaidr(thisMaidr) {
-  // conditions:
-  // - maidr isn't enabled (check if singleMaidr is undefined or false)
-  // - the chart we're moving to isn't the same as the one we're on
-  // note: if we move from one to another, destroy the current first
-
   if (typeof singleMaidr == 'undefined') {
     // not enabled
     InitMaidr(thisMaidr);
@@ -141,14 +141,15 @@ function ShouldWeInitMaidr(thisMaidr) {
 }
 
 /**
- * Determines whether Maidr should be destroyed based on the tab movement.
+ * Determines whether Maidr should be destroyed based conditions: 
+   - we've tabbed away from the chart or any component
+   - we're allowed to tab within the system (ie, braille input, review mode, etc)
  * If tab movement is 0, do nothing. If tab movement is 1 or -1, move to before/after and then destroy.
- * @param {Event} e - The blur event.
+ * @param {Event} e - The blur event from the Tab key that triggers this function.
  */
 function ShouldWeDestroyMaidr(e) {
-  // conditions: we've tabbed away from the chart or any component
-
-  // timeout to delay blur event. I forget why this is necessary, but it is
+  // timeout to delay blur event.
+  // I forget why this is necessary, but it is. - smm
   setTimeout(() => {
     if (constants.tabMovement == 0) {
       // do nothing, this is an allowed move
@@ -191,7 +192,7 @@ function FocusBeforeOrAfter() {
 }
 
 /**
- * Removes all events, global variables, and chart components associated with Maidr.
+ * Removes all events, global variables, and chart components associated with Maidr, resetting it to its uninitialized state.
  */
 function DestroyMaidr() {
   // chart cleanup
@@ -270,6 +271,7 @@ function KillAutoplayEvent(e) {
 
 /**
  * Adds all events and post load events to the DOM elements.
+ * Assumes that all events are in constants.events and all post load events are in constants.postLoadEvents.
  */
 function SetEvents() {
   // add all events
@@ -310,10 +312,15 @@ function SetEvents() {
 }
 
 /**
- * Initializes the chart components by creating a structure with a main container and a chart container,
- * updating the parents from just chart to main container > chart container > chart, and setting various
- * page elements and attributes. Also creates a braille input, an info aria live region, announcements,
- * an end chime audio element, and a review mode form field.
+ * Initializes the html chart components needed, such as:
+ * - Creates a structure with a main container and a chart container
+ * - Resets the parents from just chart to main container > chart container > chart
+ * - Creates a braille input
+ * - Creates an info aria live region
+ * - Creates announcements aria live region
+ * - Creates a review mode form field
+ * - Also sets the constants associated with these elements
+ *
  */
 function CreateChartComponents() {
   // init html stuff. aria live regions, braille input, etc

src/js/scatterplot.js

@@ -1,7 +1,3 @@
-document.addEventListener('DOMContentLoaded', function (e) {
-  // we wrap in DOMContentLoaded to make sure everything has loaded before we run anything
-});
-
 /**
  * A class representing a scatter plot.
  * @class

src/js/segmented.js

@@ -177,8 +177,6 @@ class Segmented {
    * Creates another y level that is the sum of all the other levels.
    */
   CreateSummaryLevel() {
-    // create another y level that is the sum of all the other levels
-
     for (let i = 0; i < this.plotData.length; i++) {
       let sum = 0;
       for (let j = 0; j < this.plotData[i].length; j++) {
@@ -194,8 +192,6 @@ class Segmented {
    * Creates another y level that plays all the other levels separately.
    */
   CreateAllLevel() {
-    // create another y level that plays all the other levels seperately
-
     for (let i = 0; i < this.plotData.length; i++) {
       let all = [];
       for (let j = 0; j < this.fill.length; j++) {