Merge branch 'main' into issue-5139-docs-alt-to-describe

Author: lm-n

contributor_docs/inline_documentation.md

@@ -189,6 +189,7 @@ noFill();
 arc(50, 55, 60, 60, HALF_PI, PI);
 arc(50, 55, 70, 70, PI, PI+QUARTER_PI);
 arc(50, 55, 80, 80, PI+QUARTER_PI, TWO_PI);
+describe('shattered outline of ellipse created using four arcs');
 </code>
 </div>
 ```
@@ -200,19 +201,28 @@ by a line break.
 ```
 @example
 <div>
-<code>arc(50, 50, 80, 80, 0, PI+QUARTER_PI, OPEN);</code>
+<code>
+arc(50, 50, 80, 80, 0, PI+QUARTER_PI, OPEN);
+describe('ellipse created using arc with its top right open');
+</code>
 </div>
 
 <div>
-<code>arc(50, 50, 80, 80, 0, PI, OPEN);</code>
+<code>
+arc(50, 50, 80, 80, 0, PI, OPEN);
+describe('bottom half of an ellipse created using arc');
+</code>
 </div>
 ```
 
 If you do not want the example to execute your code (i.e. you just want the code to show up), include the class "norender" in the div:
 ```
 @example
 <div class="norender">
-<code>arc(50, 50, 80, 80, 0, PI+QUARTER_PI, OPEN);</code>
+<code>
+arc(50, 50, 80, 80, 0, PI+QUARTER_PI, OPEN);
+describe('ellipse created using arc with its top right open');
+</code>
 </div>
 ```
 
@@ -230,8 +240,42 @@ function setup() {
 
 If you need to link to external asset files, put them in [/docs/yuidoc-p5-theme/assets](https://github.com/processing/p5.js/tree/main/docs/yuidoc-p5-theme/assets) and then link to them with "assets/filename.ext" in the code. See the [tint example](http://p5js.org/reference/#/p5/tint).
 
-### Adding alt-text
-Finally, for every example you add, please add [alt-text](https://moz.com/learn/seo/alt-text) so visually impaired users can understand what the example is showing on the screen. This can be added with the tag `@alt` at the end of all of the examples for a given function (not an individual `@alt` tag under each), add a line break to separate the descriptions for multiple examples.
+### Add a canvas description using describe()
+Finally, for every example you add, you are required to use the p5.js function `describe()` in the example to create a screen-reader accessible description for the canvas. Include only one parameter: a string with a brief description of what is happening on the canvas. Do NOT add a second parameter.
+```
+@example
+<div>
+<code>
+let xoff = 0.0;
+function draw() {
+  background(204);
+  xoff = xoff + 0.01;
+  let n = noise(xoff) * width;
+  line(n, 0, n, height);
+  decribe('vertical line moves left to right with updating noise values');
+}
+</code>
+</div>
+
+<div>
+<code>
+let noiseScale=0.02;
+function draw() {
+  background(0);
+  for (let x=0; x < width; x++) {
+    let noiseVal = noise((mouseX+x)*noiseScale, mouseY*noiseScale);
+    stroke(noiseVal*255);
+    line(x, mouseY+noiseVal*80, x, height);
+  }
+  describe('horizontal wave pattern effected by mouse x-position & updating noise values');
+}
+</code>
+</div>
+
+```
+For more on `describe()` visit the [web accessibility contributor docs](https://p5js.org/contributor-docs/#/web_accessibility?id=user-generated-accessible-canvas-descriptions).
+
+Previous documentation guidelines required adding [alt-text](https://moz.com/learn/seo/alt-text) to create screen-reader accessible canvas description. THIS IS NO LONGER RECOMMENDED. ALWAYS USE `describe()`. Previously, alt-text was added with the tag `@alt` at the end of all of the examples for a given function (not an individual `@alt` tag under each), and an added a line break to separate the descriptions for multiple examples. 
 ```
 @example
 <div>

src/color/setting.js

@@ -40,15 +40,15 @@ import './p5.Color';
  * <code>
  * // Grayscale integer value
  * background(51);
- * describe('canvas with darkest charcoal grey background.');
+ * describe('canvas with darkest charcoal grey background');
  * </code>
  * </div>
  *
  * <div>
  * <code>
  * // R, G & B integer values
  * background(255, 204, 0);
- * describe('canvas with yellow background.');
+ * describe('canvas with yellow background');
  * </code>
  * </div>
  *
@@ -57,73 +57,74 @@ import './p5.Color';
  * // H, S & B integer values
  * colorMode(HSB);
  * background(255, 204, 100);
- * describe('canvas with royal blue background.');
+ * describe('canvas with royal blue background');
  * </code>
  * </div>
  *
  * <div>
  * <code>
  * // Named SVG/CSS color string
  * background('red');
- * describe('canvas with red background.');
+ * describe('canvas with red background');
  * </code>
  * </div>
  *
  * <div>
  * <code>
  * // three-digit hexadecimal RGB notation
  * background('#fae');
- * describe('canvas with pink background.');
+ * describe('canvas with pink background');
  * </code>
  * </div>
  *
  * <div>
  * <code>
  * // six-digit hexadecimal RGB notation
  * background('#222222');
- * describe('canvas with black background.');
+ * describe('canvas with black background');
  * </code>
  * </div>
  *
  * <div>
  * <code>
  * // integer RGB notation
  * background('rgb(0,255,0)');
- * describe('canvas with bright green background.');
+ * describe('canvas with bright green background');
  * </code>
  * </div>
  *
  * <div>
  * <code>
  * // integer RGBA notation
  * background('rgba(0,255,0, 0.25)');
- * describe('canvas with soft green background.');
+ * describe('canvas with soft green background');
  * </code>
  * </div>
  *
  * <div>
  * <code>
  * // percentage RGB notation
  * background('rgb(100%,0%,10%)');
- * describe('canvas with red background.');
+ * describe('canvas with red background');
  * </code>
  * </div>
  *
  * <div>
  * <code>
  * // percentage RGBA notation
  * background('rgba(100%,0%,100%,0.5)');
- * describe('canvas with light purple background.');
+ * describe('canvas with light purple background');
  * </code>
  * </div>
  *
  * <div>
  * <code>
  * // p5 Color object
  * background(color(0, 0, 255));
- * describe('canvas with blue background.');
+ * describe('canvas with blue background');
  * </code>
  * </div>
+ *
  */
 
 /**
@@ -203,11 +204,13 @@ p5.prototype.background = function(...args) {
  * function mousePressed() {
  *   clear();
  *   background(128);
+ *   describe(
+ *     'canvas is cleared, small white ellipse is drawn at mouse X and mouse Y'
+ *   );
  * }
  * </code>
  * </div>
  *
- *
  * @param {Number} r normalized red val.
  * @param {Number} g normalized green val.
  * @param {Number} b normalized blue val.
@@ -253,8 +256,9 @@ p5.prototype.clear = function(...args) {
  *     point(i, j);
  *   }
  * }
- * describe(`Green to red gradient from bottom L to top R.
- * Shading originates from top left.`);
+ * describe(
+ *   'Green to red gradient from bottom left to top right with shading from top left'
+ * );
  * </code>
  * </div>
  *
@@ -280,7 +284,7 @@ p5.prototype.clear = function(...args) {
  * colorMode(RGB, 1);
  * let myColor = c._getRed();
  * text(myColor, 10, 10, 80, 80);
- * describe('unknown image.');
+ * describe('value of color red 0.4980... written on canvas');
  * </code>
  * </div>
  *
@@ -293,11 +297,10 @@ p5.prototype.clear = function(...args) {
  * stroke(255, 0, 10, 0.3);
  * ellipse(40, 40, 50, 50);
  * ellipse(50, 50, 40, 40);
- * describe(`50×50 ellipse at middle L & 40×40 ellipse at center.
- * Translucent pink outlines.`);
+ * describe('two translucent pink ellipse outlines at middle left and at center');
  * </code>
  * </div>
-
+ *
  */
 
 /**
@@ -373,8 +376,7 @@ p5.prototype.colorMode = function(mode, max1, max2, max3, maxA) {
  * // Grayscale integer value
  * fill(51);
  * rect(20, 20, 60, 60);
- * describe(`60×60 dark charcoal grey rect with black outline in center
- * of canvas.`);
+ * describe('dark charcoal grey rect with black outline in center of canvas');
  * </code>
  * </div>
  *
@@ -383,7 +385,7 @@ p5.prototype.colorMode = function(mode, max1, max2, max3, maxA) {
  * // R, G & B integer values
  * fill(255, 204, 0);
  * rect(20, 20, 60, 60);
- * describe('60×60 yellow rect with black outline in center of canvas.');
+ * describe('yellow rect with black outline in center of canvas');
  * </code>
  * </div>
  *
@@ -393,7 +395,7 @@ p5.prototype.colorMode = function(mode, max1, max2, max3, maxA) {
  * colorMode(HSB);
  * fill(255, 204, 100);
  * rect(20, 20, 60, 60);
- * describe('60×60 royal blue rect with black outline in center of canvas.');
+ * describe('royal blue rect with black outline in center of canvas');
  * </code>
  * </div>
  *
@@ -402,7 +404,7 @@ p5.prototype.colorMode = function(mode, max1, max2, max3, maxA) {
  * // Named SVG/CSS color string
  * fill('red');
  * rect(20, 20, 60, 60);
- * describe('60×60 red rect with black outline in center of canvas.');
+ * describe('red rect with black outline in center of canvas');
  * </code>
  * </div>
  *
@@ -411,7 +413,7 @@ p5.prototype.colorMode = function(mode, max1, max2, max3, maxA) {
  * // three-digit hexadecimal RGB notation
  * fill('#fae');
  * rect(20, 20, 60, 60);
- * describe('60×60 pink rect with black outline in center of canvas.');
+ * describe('pink rect with black outline in center of canvas');
  * </code>
  * </div>
  *
@@ -420,7 +422,7 @@ p5.prototype.colorMode = function(mode, max1, max2, max3, maxA) {
  * // six-digit hexadecimal RGB notation
  * fill('#222222');
  * rect(20, 20, 60, 60);
- * describe('60×60 black rect with black outline in center of canvas.');
+ * describe('black rect with black outline in center of canvas');
  * </code>
  * </div>
  *
@@ -429,7 +431,7 @@ p5.prototype.colorMode = function(mode, max1, max2, max3, maxA) {
  * // integer RGB notation
  * fill('rgb(0,255,0)');
  * rect(20, 20, 60, 60);
- * describe('60×60 light green rect with black outline in center of canvas.');
+ * describe('bright green rect with black outline in center of canvas');
  * </code>
  * </div>
  *
@@ -438,7 +440,7 @@ p5.prototype.colorMode = function(mode, max1, max2, max3, maxA) {
  * // integer RGBA notation
  * fill('rgba(0,255,0, 0.25)');
  * rect(20, 20, 60, 60);
- * describe('60×60 soft green rect with black outline in center of canvas.');
+ * describe('soft green rect with black outline in center of canvas');
  * </code>
  * </div>
  *
@@ -447,7 +449,7 @@ p5.prototype.colorMode = function(mode, max1, max2, max3, maxA) {
  * // percentage RGB notation
  * fill('rgb(100%,0%,10%)');
  * rect(20, 20, 60, 60);
- * describe('60×60 red rect with black outline in center of canvas.');
+ * describe('red rect with black outline in center of canvas');
  * </code>
  * </div>
  *
@@ -456,7 +458,7 @@ p5.prototype.colorMode = function(mode, max1, max2, max3, maxA) {
  * // percentage RGBA notation
  * fill('rgba(100%,0%,100%,0.5)');
  * rect(20, 20, 60, 60);
- * describe('60×60 dark fuchsia rect with black outline in center of canvas.');
+ * describe('dark fuchsia rect with black outline in center of canvas');
  * </code>
  * </div>
  *
@@ -465,7 +467,7 @@ p5.prototype.colorMode = function(mode, max1, max2, max3, maxA) {
  * // p5 Color object
  * fill(color(0, 0, 255));
  * rect(20, 20, 60, 60);
- * describe('60×60 blue rect with black outline in center of canvas.');
+ * describe('blue rect with black outline in center of canvas');
  * </code>
  * </div>
  */