comments on colorNamer and describe

Author: Luis Morales-Navarro

contributor_docs/web_accessibility.md

@@ -83,14 +83,12 @@ The `describe()` function creates a screen reader accessible description for the
 
 `describe()` is supported by several functions in [src/accessibility/describe.js](https://github.com/processing/p5.js/blob/main/src/accessibility/describe.js):
 * `_descriptionText()`: Checks that text is not `LABEL` or `FALLBACK` and ensures text ends with a punctuation mark. If the text does not end with '.', ',', ';', '?', '!', this function adds a '.' at the end of the string. Returns text.
-* `_describeFallbackHTML()`: Creates fallback HTML structure for the canvas. 
-* `_describeLabelHTML()`: This function is only called when the second parameter of `_describe()` is `LABEL`. It creates a div adjacent to the canvas element for the description text.
+* `_describeHTML()`: Creates fallback HTML structure for the canvas. If the second parameter of `_describe()` is `LABEL`, this function creates a div adjacent to the canvas element for the description text.
 
 ### describeElement()
 The `describeElement()` function creates a screen reader accessible description for sketch elements or groups of shapes that create meaning together. The first parameter should be a string with the name of the element, the second parameter should be a string with the description of the element. The third parameter is optional. If specified, it determines how the description is displayed. All element descriptions become part of the sub DOM of the canvas element. If a user passes `LABEL` as a third parameter, an additional div with the element description adjacent to the canvas is created. 
 
 `describeElement()` is supported by several functions in [src/accessibility/describe.js](https://github.com/processing/p5.js/blob/main/src/accessibility/describe.js):
 * `_elementName()`: Checks that element name is not `LABEL` or `FALLBACK` and ensures text ends with a colon. Returns element name.
 * `_descriptionText()`: Checks that text is not `LABEL` or `FALLBACK` and ensures text ends with a punctuation mark. If the text does not end with '.', ',', ';', '?', '!', this function adds a '.' at the end of the string. Returns text.
-* `_describeElementFallbackHTML()`: Creates fallback HTML structure for the canvas. 
-* `_describeElementLabelHTML()`: This function is only called when the second parameter of `_describeElement()` is `LABEL`. It creates a div adjacent to the canvas element for the description text.
+* `_describeElementHTML()`: Creates fallback HTML structure for the canvas. When the second parameter of `_describeElement()` is `LABEL`, this function creates a div adjacent to the canvas element for the descriptions.

src/accessibility/color_namer.js

@@ -622,19 +622,25 @@ const colorLookUp = [
 //returns text with color name
 function _calculateColor(hsb) {
   let colortext;
+  //round hue
   if (hsb[0] !== 0) {
     hsb[0] = Math.round(hsb[0] * 100);
     let hue = hsb[0].toString().split('');
     const last = hue.length - 1;
     hue[last] = parseInt(hue[last]);
+    //if last digit of hue is < 2.5 make it 0
     if (hue[last] < 2.5) {
       hue[last] = 0;
+      //if last digit of hue is >= 2.5 and less than 7.5 make it 5
     } else if (hue[last] >= 2.5 && hue[last] < 7.5) {
       hue[last] = 5;
     }
+    //if hue only has two digits
     if (hue.length === 2) {
       hue[0] = parseInt(hue[0]);
+      //if last is greater than 7.5
       if (hue[last] >= 7.5) {
+        //add one to the tens
         hue[last] = 0;
         hue[0] = hue[0] + 1;
       }
@@ -647,6 +653,9 @@ function _calculateColor(hsb) {
       }
     }
   }
+  //map brightness from 0 to 1
+  hsb[2] = hsb[2] / 255;
+  //round saturation and brightness
   for (let i = hsb.length - 1; i >= 1; i--) {
     if (hsb[i] <= 0.25) {
       hsb[i] = 0;
@@ -656,11 +665,14 @@ function _calculateColor(hsb) {
       hsb[i] = 1;
     }
   }
+  //after rounding, if the values are hue 0, saturation 0 and brightness 1
+  //look at color exceptions which includes several tones from white to gray
   if (hsb[0] === 0 && hsb[1] === 0 && hsb[2] === 1) {
+    //round original hsb values
     for (let i = 2; i >= 0; i--) {
-      //for (let i = originalHSB.length - 1; i >= 0; i--) {
       originalHSB[i] = Math.round(originalHSB[i] * 10000) / 10000;
     }
+    //compare with the values in the colorExceptions array
     for (let e = 0; e < colorExceptions.length; e++) {
       if (
         colorExceptions[e].h === originalHSB[0] &&
@@ -670,10 +682,12 @@ function _calculateColor(hsb) {
         colortext = colorExceptions[e].name;
         break;
       } else {
+        //if there is no match return white
         colortext = 'white';
       }
     }
   } else {
+    //otherwise, compare with values in colorLookUp
     for (let i = 0; i < colorLookUp.length; i++) {
       if (
         colorLookUp[i].h === hsb[0] &&

src/accessibility/describe.js

@@ -239,7 +239,7 @@ function _descriptionText(text) {
  * Helper functions for describe()
  */
 
-//creates fallback HTML structure
+//creates HTML structure for canvas descriptions
 p5.prototype._describeHTML = function(type, text) {
   const cnvId = this.canvas.id;
   if (type === 'fallback') {
@@ -327,7 +327,7 @@ function _elementName(name) {
   return name;
 }
 
-//creates fallback HTML structure for element descriptions
+//creates HTML structure for element descriptions
 p5.prototype._describeElementHTML = function(type, name, text) {
   const cnvId = this.canvas.id;
   if (type === 'fallback') {

test/unit/accessibility/outputs.js

@@ -260,7 +260,7 @@ suite('outputs', function() {
     });
     test('should create text output for point()', function() {
       return new Promise(function(resolve, reject) {
-        expected = 'fuchsia point, location = bottom right';
+        expected = 'dark fuchsia point, location = bottom right';
         new p5(function(p) {
           p.setup = function() {
             let cnv = p.createCanvas(100, 100);