Edit docs for accessibility

src/accessibility/describe.js

@@ -16,53 +16,51 @@ const labelTableId = '_labelTable'; //Label Table
 const labelTableElId = '_lte_'; //Label Table Element
 
 /**
- * Creates a screen reader accessible description for the canvas.
- * The first parameter should be a string with a description of the canvas.
- * The second parameter is optional. If specified, it determines how the
- * description is displayed.
+ * Creates a screen reader-accessible description for the canvas.
  *
- * <code class="language-javascript">describe(text, LABEL)</code> displays
- * the description to all users as a <a
- * href="https://en.wikipedia.org/wiki/Museum_label" target="_blank">
- * tombstone or exhibit label/caption</a> in a div
- * adjacent to the canvas. You can style it as you wish in your CSS.
+ * The first parameter, `text`, is the description of the canvas.
  *
- * <code class="language-javascript">describe(text, FALLBACK)</code> makes the
- * description accessible to screen-reader users only, in
- * <a href="https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Hit_regions_and_accessibility" target="_blank">
- * a sub DOM inside the canvas element</a>. If a second parameter is not
- * specified, by default, the description will only be available to
- * screen-reader users.
+ * The second parameter, `display`, is optional. It determines how the
+ * description is displayed. If `LABEL` is passed, as in
+ * `describe('A description.', LABEL)`, the description will be visible in
+ * a div element next to the canvas. If `FALLBACK` is passed, as in
+ * `describe('A description.', FALLBACK)`, the description will only be
+ * visible to screen readers. This is the default mode.
+ *
+ * Read
+ * <a href="/learn/labeling-canvases.html">How to label your p5.js code</a> to
+ * learn more about making sketches accessible.
  *
  * @method describe
- * @param  {String} text      description of the canvas
- * @param  {Constant} [display] either LABEL or FALLBACK
+ * @param  {String} text        description of the canvas.
+ * @param  {Constant} [display] either LABEL or FALLBACK.
  *
  * @example
  * <div>
  * <code>
- * describe('pink square with red heart in the bottom right corner');
- * background('pink');
- * fill('red');
- * noStroke();
- * ellipse(67, 67, 20, 20);
- * ellipse(83, 67, 20, 20);
- * triangle(91, 73, 75, 95, 59, 73);
+ * function setup() {
+ *   background('pink');
+ *   fill('red');
+ *   noStroke();
+ *   circle(67, 67, 20);
+ *   circle(83, 67, 20);
+ *   triangle(91, 73, 75, 95, 59, 73);
+ *
+ *   describe('A pink square with a red heart in the bottom-right corner.');
+ * }
  * </code>
  * </div>
  *
  * <div>
  * <code>
- * let x = 0;
  * function draw() {
- *   if (x > 100) {
- *     x = 0;
- *   }
- *   background(220);
+ *   background(200);
+ *
+ *   let x = frameCount % 100;
  *   fill(0, 255, 0);
- *   ellipse(x, 50, 40, 40);
- *   x = x + 0.1;
- *   describe('green circle at x pos ' + round(x) + ' moving to the right');
+ *   circle(x, 50, 40);
+ *
+ *   describe('A green circle moves from left to right on a gray square. It restarts on the left edge after reaching the right edge.');
  * }
  * </code>
  * </div>
@@ -112,45 +110,50 @@ p5.prototype.describe = function(text, display) {
 };
 
 /**
- * This function creates a screen-reader accessible
- * description for elements —shapes or groups of shapes that create
- * meaning together— in the canvas. The first paramater should
- * be the name of the element. The second parameter should be a string
- * with a description of the element. The third parameter is optional.
- * If specified, it determines how the element description is displayed.
+ * Creates a screen reader-accessible description for elements in the canvas.
+ * Elements are shapes or groups of shapes that create meaning together.
+ *
+ * The first parameter, `name`, is the name of the element.
  *
- * <code class="language-javascript">describeElement(name, text, LABEL)</code>
- * displays the element description to all users as a
- * <a href="https://en.wikipedia.org/wiki/Museum_label" target="_blank">
- * tombstone or exhibit label/caption</a> in a div
- * adjacent to the canvas. You can style it as you wish in your CSS.
+ * The second parameter, `text`, is the description of the element.
  *
- * <code class="language-javascript">describeElement(name, text, FALLBACK)</code>
- * makes the element description accessible to screen-reader users
- * only, in <a href="https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Hit_regions_and_accessibility" target="_blank">
- * a sub DOM inside the canvas element</a>. If a second parameter is not
- * specified, by default, the element description will only be available
- * to screen-reader users.
+ * The third parameter, `display`, is optional. It determines how the
+ * description is displayed. If `LABEL` is passed, as in
+ * `describe('A description.', LABEL)`, the description will be visible in
+ * a div element next to the canvas. Using `LABEL` creates unhelpful
+ * duplicates for screen readers. Only use `LABEL` during development. If
+ * `FALLBACK` is passed, as in `describe('A description.', FALLBACK)`, the
+ * description will only be visible to screen readers. This is the default
+ * mode.
+ *
+ * Read
+ * <a href="/learn/labeling-canvases.html">How to label your p5.js code</a> to
+ * learn more about making sketches accessible.
  *
  * @method describeElement
- * @param  {String} name      name of the element
- * @param  {String} text      description of the element
- * @param  {Constant} [display] either LABEL or FALLBACK
+ * @param  {String} name        name of the element.
+ * @param  {String} text        description of the element.
+ * @param  {Constant} [display] either LABEL or FALLBACK.
  *
  * @example
  * <div>
  * <code>
- * describe('Heart and yellow circle over pink background');
- * noStroke();
- * background('pink');
- * describeElement('Circle', 'Yellow circle in the top left corner');
- * fill('yellow');
- * ellipse(25, 25, 40, 40);
- * describeElement('Heart', 'red heart in the bottom right corner');
- * fill('red');
- * ellipse(66.6, 66.6, 20, 20);
- * ellipse(83.2, 66.6, 20, 20);
- * triangle(91.2, 72.6, 75, 95, 58.6, 72.6);
+ * function setup() {
+ *   background('pink');
+ *
+ *   noStroke();
+ *   describeElement('Circle', 'A yellow circle in the top-left corner.');
+ *   fill('yellow');
+ *   circle(25, 25, 40);
+ *
+ *   describeElement('Heart', 'A red heart in the bottom-right corner.');
+ *   fill('red');
+ *   circle(66.6, 66.6, 20);
+ *   circle(83.2, 66.6, 20);
+ *   triangle(91.2, 72.6, 75, 95, 58.6, 72.6);
+ *
+ *   describe('A red heart and yellow circle over a pink background.');
+ * }
  * </code>
  * </div>
  */

src/accessibility/outputs.js

@@ -8,58 +8,67 @@
 import p5 from '../core/main';
 
 /**
- * <code class="language-javascript">textOutput()</code> creates a screenreader
- * accessible output that describes the shapes present on the canvas.
- * The general description of the canvas includes canvas size,
- * canvas color, and number of elements in the canvas
- * (example: 'Your output is a, 400 by 400 pixels, lavender blue
- * canvas containing the following 4 shapes:'). This description
- * is followed by a list of shapes where the color, position, and area
- * of each shape are described (example: "orange ellipse at top left
- * covering 1% of the canvas"). Each element can be selected to get
- * more details. A table of elements is also provided. In this table,
- * shape, color, location, coordinates and area are described
- * (example: "orange ellipse location=top left area=2").
+ * Creates a screen reader-accessible description for shapes on the canvas.
+ * `textOutput()` adds a general description, list of shapes, and
+ * table of shapes to the web page.
  *
- * <code class="language-javascript">textOutput()</code> and <code class="language-javascript">textOutput(FALLBACK)</code>
- * make the output available in <a href="https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Hit_regions_and_accessibility" target="_blank">
- * a sub DOM inside the canvas element</a> which is accessible to screen readers.
- * <code class="language-javascript">textOutput(LABEL)</code> creates an
- * additional div with the output adjacent to the canvas, this is useful
- * for non-screen reader users that might want to display the output outside
- * of the canvas' sub DOM as they code. However, using LABEL will create
- * unnecessary redundancy for screen reader users. We recommend using LABEL
- * only as part of the development process of a sketch and removing it before
- * publishing or sharing with screen reader users.
+ * The general description includes the canvas size, canvas color, and number
+ * of shapes. For example,
+ * `Your output is a, 100 by 100 pixels, gray canvas containing the following 2 shapes:`.
+ *
+ * A list of shapes follows the general description. The list describes the
+ * color, location, and area of each shape. For example,
+ * `a red circle at middle covering 3% of the canvas`. Each shape can be
+ * selected to get more details.
+ *
+ * `textOutput()` uses its table of shapes as a list. The table describes the
+ * shape, color, location, coordinates and area. For example,
+ * `red circle location = middle area = 3%`. This is different from
+ * <a href="#/p5/gridOutput">gridOutput()</a>, which uses its table as a grid.
+ *
+ * The `display` parameter is optional. It determines how the description is
+ * displayed. If `LABEL` is passed, as in `textOutput(LABEL)`, the description
+ * will be visible in a div element next to the canvas. Using `LABEL` creates
+ * unhelpful duplicates for screen readers. Only use `LABEL` during
+ * development. If `FALLBACK` is passed, as in `textOutput(FALLBACK)`, the
+ * description will only be visible to screen readers. This is the default
+ * mode.
+ *
+ * Read
+ * <a href="/learn/labeling-canvases.html">How to label your p5.js code</a> to
+ * learn more about making sketches accessible.
  *
  * @method textOutput
- * @param  {Constant} [display] either FALLBACK or LABEL
+ * @param  {Constant} [display] either FALLBACK or LABEL.
  *
  * @example
  * <div>
  * <code>
- * textOutput();
- * background(148, 196, 0);
- * fill(255, 0, 0);
- * ellipse(20, 20, 20, 20);
- * fill(0, 0, 255);
- * rect(50, 50, 50, 50);
+ * function setup() {
+ *   textOutput();
+ *   background(200);
+ *   fill(255, 0, 0);
+ *   circle(20, 20, 20);
+ *   fill(0, 0, 255);
+ *   square(50, 50, 50);
+ *
+ *   describe('A red circle and a blue square on a gray background.');
+ * }
  * </code>
  * </div>
  *
- *
  * <div>
  * <code>
- * let x = 0;
  * function draw() {
  *   textOutput();
- *   background(148, 196, 0);
+ *   background(200);
+ *   let x = frameCount * 0.1;
  *   fill(255, 0, 0);
- *   ellipse(x, 20, 20, 20);
+ *   circle(x, 20, 20);
  *   fill(0, 0, 255);
- *   rect(50, 50, 50, 50);
- *   ellipse(20, 20, 20, 20);
- *   x += 0.1;
+ *   square(50, 50, 50);
+ *
+ *   describe('A red circle moves from left to right above a blue square.');
  * }
  * </code>
  * </div>
@@ -86,59 +95,68 @@ p5.prototype.textOutput = function(display) {
 };
 
 /**
- * <code class="language-javascript">gridOutput()</code> lays out the
- * content of the canvas in the form of a grid (html table) based
- * on the spatial location of each shape. A brief
- * description of the canvas is available before the table output.
- * This description includes: color of the background, size of the canvas,
- * number of objects, and object types (example: "lavender blue canvas is
- * 200 by 200 and contains 4 objects - 3 ellipses 1 rectangle"). The grid
- * describes the content spatially, each element is placed on a cell of the
- * table depending on its position. Within each cell an element the color
- * and type of shape of that element are available (example: "orange ellipse").
- * These descriptions can be selected individually to get more details.
- * A list of elements where shape, color, location, and area are described
- * (example: "orange ellipse location=top left area=1%") is also available.
+ * Creates a screen reader-accessible description for shapes on the canvas.
+ * `gridOutput()` adds a general description, table of shapes, and list of
+ * shapes to the web page.
  *
- * <code class="language-javascript">gridOutput()</code> and <code class="language-javascript">gridOutput(FALLBACK)</code>
- * make the output available in <a href="https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Hit_regions_and_accessibility" target="_blank">
- * a sub DOM inside the canvas element</a> which is accessible to screen readers.
- * <code class="language-javascript">gridOutput(LABEL)</code> creates an
- * additional div with the output adjacent to the canvas, this is useful
- * for non-screen reader users that might want to display the output outside
- * of the canvas' sub DOM as they code. However, using LABEL will create
- * unnecessary redundancy for screen reader users. We recommend using LABEL
- * only as part of the development process of a sketch and removing it before
- * publishing or sharing with screen reader users.
+ * The general description includes the canvas size, canvas color, and number of
+ * shapes. For example,
+ * `gray canvas, 100 by 100 pixels, contains 2 shapes:  1 circle 1 square`.
+ *
+ * `gridOutput()` uses its table of shapes as a grid. Each shape in the grid
+ * is placed in a cell whose row and column correspond to the shape's location
+ * on the canvas. The grid cells describe the color and type of shape at that
+ * location. For example, `red circle`. These descriptions can be selected
+ * individually to get more details. This is different from
+ * <a href="#/p5/textOutput">textOutput()</a>, which uses its table as a list.
+ *
+ * A list of shapes follows the table. The list describes the color, type,
+ * location, and area of each shape. For example,
+ * `red circle, location = middle, area = 3 %`.
+ *
+ * The `display` parameter is optional. It determines how the description is
+ * displayed. If `LABEL` is passed, as in `gridOutput(LABEL)`, the description
+ * will be visible in a div element next to the canvas. Using `LABEL` creates
+ * unhelpful duplicates for screen readers. Only use `LABEL` during
+ * development. If `FALLBACK` is passed, as in `gridOutput(FALLBACK)`, the
+ * description will only be visible to screen readers. This is the default
+ * mode.
+ *
+ * Read
+ * <a href="/learn/labeling-canvases.html">How to label your p5.js code</a> to
+ * learn more about making sketches accessible.
  *
  * @method gridOutput
- * @param  {Constant} [display] either FALLBACK or LABEL
+ * @param  {Constant} [display] either FALLBACK or LABEL.
  *
  * @example
  * <div>
  * <code>
- * gridOutput();
- * background(148, 196, 0);
- * fill(255, 0, 0);
- * ellipse(20, 20, 20, 20);
- * fill(0, 0, 255);
- * rect(50, 50, 50, 50);
+ * function setup() {
+ *   gridOutput();
+ *   background(200);
+ *   fill(255, 0, 0);
+ *   circle(20, 20, 20);
+ *   fill(0, 0, 255);
+ *   square(50, 50, 50);
+ *
+ *   describe('A red circle and a blue square on a gray background.');
+ * }
  * </code>
  * </div>
  *
- *
  * <div>
  * <code>
- * let x = 0;
  * function draw() {
  *   gridOutput();
- *   background(148, 196, 0);
+ *   background(200);
+ *   let x = frameCount * 0.1;
  *   fill(255, 0, 0);
- *   ellipse(x, 20, 20, 20);
+ *   circle(x, 20, 20);
  *   fill(0, 0, 255);
- *   rect(50, 50, 50, 50);
- *   ellipse(20, 20, 20, 20);
- *   x += 0.1;
+ *   square(50, 50, 50);
+ *
+ *   describe('A red circle moves from left to right above a blue square.');
  * }
  * </code>
  * </div>