From f4f4c61cdbe4dd0c78845b272338f88f8620374c Mon Sep 17 00:00:00 2001 From: ellvix Date: Sun, 19 Nov 2023 17:06:11 -0700 Subject: [PATCH 1/2] Updated documentation --- src/js/audio.js | 10 +++++---- src/js/boxplot.js | 25 ++++++----------------- src/js/constants.js | 13 ++---------- src/js/display.js | 7 +++++-- src/js/histogram.js | 8 -------- src/js/init.js | 47 +++++++++++++++++++++++++------------------ src/js/scatterplot.js | 4 ---- src/js/segmented.js | 4 ---- 8 files changed, 46 insertions(+), 72 deletions(-) diff --git a/src/js/audio.js b/src/js/audio.js index 33e389de..c1d18693 100644 --- a/src/js/audio.js +++ b/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; diff --git a/src/js/boxplot.js b/src/js/boxplot.js index 4c439e37..b7fa31d2 100644 --- a/src/js/boxplot.js +++ b/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 diff --git a/src/js/constants.js b/src/js/constants.js index e4a8e13e..d0ba0097 100644 --- a/src/js/constants.js +++ b/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 diff --git a/src/js/display.js b/src/js/display.js index 529d26ba..0fb59c61 100644 --- a/src/js/display.js +++ b/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. diff --git a/src/js/histogram.js b/src/js/histogram.js index 196b24f0..41ca3ea5 100644 --- a/src/js/histogram.js +++ b/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 diff --git a/src/js/init.js b/src/js/init.js index d3345662..4105c810 100644 --- a/src/js/init.js +++ b/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 diff --git a/src/js/scatterplot.js b/src/js/scatterplot.js index 20f31f56..0e2e3b7b 100644 --- a/src/js/scatterplot.js +++ b/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 diff --git a/src/js/segmented.js b/src/js/segmented.js index ce1f912b..4ae99f25 100644 --- a/src/js/segmented.js +++ b/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++) { From 25cb632ddb8bb73ae6878ed5439c2fa4437ff25c Mon Sep 17 00:00:00 2001 From: ellvix Date: Sun, 19 Nov 2023 17:07:11 -0700 Subject: [PATCH 2/2] updated changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index dd459f53..61721006 100644 --- a/CHANGELOG.md +++ b/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