From 2adf53d5d47d8abd52b85442220a3a284e60e093 Mon Sep 17 00:00:00 2001
From: Zearin <Zearin@users.noreply.github.com>
Date: Sun, 6 Feb 2022 12:29:47 -0500
Subject: [PATCH] docs(src/events): Use `describe()` instead of `@alt`

Addresses #5139
---
 src/events/acceleration.js |  72 ++++++++++----------------
 src/events/keyboard.js     |  39 ++++++--------
 src/events/mouse.js        | 102 +++++++++++++------------------------
 src/events/touch.js        |  26 ++++------
 4 files changed, 90 insertions(+), 149 deletions(-)

diff --git a/src/events/acceleration.js b/src/events/acceleration.js
index 0021609549..7ca8f371aa 100644
--- a/src/events/acceleration.js
+++ b/src/events/acceleration.js
@@ -35,11 +35,10 @@ p5.prototype.deviceOrientation =
  *   background(220, 50);
  *   fill('magenta');
  *   ellipse(width / 2, height / 2, accelerationX);
+ *   describe('Magnitude of device acceleration is displayed as ellipse size.');
  * }
  * </code>
  * </div>
- * @alt
- * Magnitude of device acceleration is displayed as ellipse size
  */
 p5.prototype.accelerationX = 0;
 
@@ -58,11 +57,10 @@ p5.prototype.accelerationX = 0;
  *   background(220, 50);
  *   fill('magenta');
  *   ellipse(width / 2, height / 2, accelerationY);
+ *   describe('Magnitude of device acceleration is displayed as ellipse size');
  * }
  * </code>
  * </div>
- * @alt
- * Magnitude of device acceleration is displayed as ellipse size
  */
 p5.prototype.accelerationY = 0;
 
@@ -82,12 +80,10 @@ p5.prototype.accelerationY = 0;
  *   background(220, 50);
  *   fill('magenta');
  *   ellipse(width / 2, height / 2, accelerationZ);
+ *   describe('Magnitude of device acceleration is displayed as ellipse size');
  * }
  * </code>
  * </div>
- *
- * @alt
- * Magnitude of device acceleration is displayed as ellipse size
  */
 p5.prototype.accelerationZ = 0;
 
@@ -157,11 +153,11 @@ p5.prototype._updatePAccelerations = function() {
  *   rotateX(radians(rotationX));
  *   //rotateY(radians(rotationY));
  *   box(200, 200, 200);
+ *   describe(`red horizontal line right, green vertical line bottom.
+ *     black background.`);
  * }
  * </code>
  * </div>
- * @alt
- * red horizontal line right, green vertical line bottom. black background.
  */
 p5.prototype.rotationX = 0;
 
@@ -190,11 +186,11 @@ p5.prototype.rotationX = 0;
  *   //rotateX(radians(rotationX));
  *   rotateY(radians(rotationY));
  *   box(200, 200, 200);
+ *   describe(`red horizontal line right, green vertical line bottom.
+ *     black background.`);
  * }
  * </code>
  * </div>
- * @alt
- * red horizontal line right, green vertical line bottom. black background.
  */
 p5.prototype.rotationY = 0;
 
@@ -224,15 +220,14 @@ p5.prototype.rotationY = 0;
  *   //rotateX(radians(rotationX));
  *   //rotateY(radians(rotationY));
  *   box(200, 200, 200);
+ *   describe(`red horizontal line right, green vertical line bottom.
+ *     black background.`);
  * }
  * </code>
  * </div>
  *
  * @property {Number} rotationZ
  * @readOnly
- *
- * @alt
- * red horizontal line right, green vertical line bottom. black background.
  */
 p5.prototype.rotationZ = 0;
 
@@ -271,12 +266,10 @@ p5.prototype.rotationZ = 0;
  * }
  *
  * print(rotateDirection);
+ * describe('no image to display.');
  * </code>
  * </div>
  *
- * @alt
- * no image to display.
- *
  * @property {Number} pRotationX
  * @readOnly
  */
@@ -316,12 +309,10 @@ p5.prototype.pRotationX = 0;
  *   rotateDirection = 'counter-clockwise';
  * }
  * print(rotateDirection);
+ * describe('no image to display.');
  * </code>
  * </div>
  *
- * @alt
- * no image to display.
- *
  * @property {Number} pRotationY
  * @readOnly
  */
@@ -357,12 +348,10 @@ p5.prototype.pRotationY = 0;
  *   rotateDirection = 'counter-clockwise';
  * }
  * print(rotateDirection);
+ * describe('no image to display.');
  * </code>
  * </div>
  *
- * @alt
- * no image to display.
- *
  * @property {Number} pRotationZ
  * @readOnly
  */
@@ -403,6 +392,10 @@ p5.prototype._updatePRotations = function() {
  * function draw() {
  *   fill(value);
  *   rect(25, 25, 50, 50);
+ *   describe(`50×50 black rect in center of canvas.
+ *     turns white on mobile when device turns`);
+ *   describe(`50×50 black rect in center of canvas.
+ *     turns white on mobile when x-axis turns`);
  * }
  * function deviceTurned() {
  *   if (turnAxis === 'X') {
@@ -415,10 +408,6 @@ p5.prototype._updatePRotations = function() {
  * }
  * </code>
  * </div>
- *
- * @alt
- * 50×50 black rect in center of canvas. turns white on mobile when device turns
- * 50×50 black rect in center of canvas. turns white on mobile when x-axis turns
  */
 p5.prototype.turnAxis = undefined;
 
@@ -446,6 +435,8 @@ let shake_threshold = 30;
  * function draw() {
  *   fill(value);
  *   rect(25, 25, 50, 50);
+ *   describe(`50×50 black rect in center of canvas.
+ *     turns white on mobile when device moves`);
  * }
  * function deviceMoved() {
  *   value = value + 5;
@@ -458,9 +449,6 @@ let shake_threshold = 30;
  * }
  * </code>
  * </div>
- *
- * @alt
- * 50×50 black rect in center of canvas. turns white on mobile when device moves
  */
 
 p5.prototype.setMoveThreshold = function(val) {
@@ -489,6 +477,8 @@ p5.prototype.setMoveThreshold = function(val) {
  * function draw() {
  *   fill(value);
  *   rect(25, 25, 50, 50);
+ *   describe(`50×50 black rect in center of canvas.
+ *     turns white on mobile when device is being shaked`);
  * }
  * function deviceMoved() {
  *   value = value + 5;
@@ -501,10 +491,6 @@ p5.prototype.setMoveThreshold = function(val) {
  * }
  * </code>
  * </div>
- *
- * @alt
- * 50×50 black rect in center of canvas. turns white on mobile when device
- * is being shaked
  */
 
 p5.prototype.setShakeThreshold = function(val) {
@@ -529,6 +515,8 @@ p5.prototype.setShakeThreshold = function(val) {
  * function draw() {
  *   fill(value);
  *   rect(25, 25, 50, 50);
+ *   describe(`50×50 black rect in center of canvas.
+ *     turns white on mobile when device moves`);
  * }
  * function deviceMoved() {
  *   value = value + 5;
@@ -538,9 +526,6 @@ p5.prototype.setShakeThreshold = function(val) {
  * }
  * </code>
  * </div>
- *
- * @alt
- * 50×50 black rect in center of canvas. turns white on mobile when device moves
  */
 
 /**
@@ -583,6 +568,10 @@ p5.prototype.setShakeThreshold = function(val) {
  * function draw() {
  *   fill(value);
  *   rect(25, 25, 50, 50);
+ *   describe(`50×50 black rect in center of canvas.
+ *     turns white on mobile when device turns`);
+ *   describe(`50×50 black rect in center of canvas.
+ *     turns white on mobile when x-axis turns`);
  * }
  * function deviceTurned() {
  *   if (turnAxis === 'X') {
@@ -595,10 +584,6 @@ p5.prototype.setShakeThreshold = function(val) {
  * }
  * </code>
  * </div>
- *
- * @alt
- * 50×50 black rect in center of canvas. turns white on mobile when device turns
- * 50×50 black rect in center of canvas. turns white on mobile when x-axis turns
  */
 
 /**
@@ -618,6 +603,8 @@ p5.prototype.setShakeThreshold = function(val) {
  * function draw() {
  *   fill(value);
  *   rect(25, 25, 50, 50);
+ *   describe(`50×50 black rect in center of canvas.
+ *     turns white on mobile when device shakes`);
  * }
  * function deviceShaken() {
  *   value = value + 5;
@@ -627,9 +614,6 @@ p5.prototype.setShakeThreshold = function(val) {
  * }
  * </code>
  * </div>
- *
- * @alt
- * 50×50 black rect in center of canvas. turns white on mobile when device shakes
  */
 
 p5.prototype._ondeviceorientation = function(e) {
diff --git a/src/events/keyboard.js b/src/events/keyboard.js
index 4ee87f313f..228567e0e1 100644
--- a/src/events/keyboard.js
+++ b/src/events/keyboard.js
@@ -23,12 +23,10 @@ import p5 from '../core/main';
  *     fill(255);
  *   }
  *   rect(25, 25, 50, 50);
+ *   describe('50×50 white rect that turns black on keypress.');
  * }
  * </code>
  * </div>
- *
- * @alt
- * 50×50 white rect that turns black on keypress.
  */
 p5.prototype.isKeyPressed = false;
 p5.prototype.keyIsPressed = false; // khan
@@ -53,11 +51,9 @@ p5.prototype.keyIsPressed = false; // khan
  * function draw() {
  *   background(200);
  *   text(key, 33, 65); // Display last key pressed.
+ *   describe('canvas displays any key value that is pressed in pink font.');
  * }
  * </code></div>
- *
- * @alt
- * canvas displays any key value that is pressed in pink font.
  */
 p5.prototype.key = '';
 
@@ -76,6 +72,8 @@ p5.prototype.key = '';
  * function draw() {
  *   fill(fillVal);
  *   rect(25, 25, 50, 50);
+ *   describe(`Grey rect center. turns white when up arrow pressed and black when down.
+ *     Display key pressed and its keyCode in a yellow box.`);
  * }
  *
  * function keyPressed() {
@@ -94,9 +92,6 @@ p5.prototype.key = '';
  *   print(key, ' ', keyCode);
  * }
  * </code></div>
- * @alt
- * Grey rect center. turns white when up arrow pressed and black when down
- * Display key pressed and its keyCode in a yellow box
  */
 p5.prototype.keyCode = 0;
 
@@ -130,6 +125,8 @@ p5.prototype.keyCode = 0;
  * function draw() {
  *   fill(value);
  *   rect(25, 25, 50, 50);
+ *   describe(`black rect center. turns white when key pressed and black
+ *     when released.`);
  * }
  * function keyPressed() {
  *   if (value === 0) {
@@ -146,6 +143,8 @@ p5.prototype.keyCode = 0;
  * function draw() {
  *   fill(value);
  *   rect(25, 25, 50, 50);
+ *   describe(`black rect center. turns white when left arrow pressed and
+ *     black when right.`);
  * }
  * function keyPressed() {
  *   if (keyCode === LEFT_ARROW) {
@@ -164,10 +163,6 @@ p5.prototype.keyCode = 0;
  * }
  * </code>
  * </div>
- *
- * @alt
- * black rect center. turns white when key pressed and black when released
- * black rect center. turns white when left arrow pressed and black when right.
  */
 p5.prototype._onkeydown = function(e) {
   if (this._downKeys[e.which]) {
@@ -203,6 +198,8 @@ p5.prototype._onkeydown = function(e) {
  * function draw() {
  *   fill(value);
  *   rect(25, 25, 50, 50);
+ *   describe(`black rect center. turns white when key pressed and black
+ *     when pressed again`);
  * }
  * function keyReleased() {
  *   if (value === 0) {
@@ -214,9 +211,6 @@ p5.prototype._onkeydown = function(e) {
  * }
  * </code>
  * </div>
- *
- * @alt
- * black rect center. turns white when key pressed and black when pressed again
  */
 p5.prototype._onkeyup = function(e) {
   this._downKeys[e.which] = false;
@@ -263,6 +257,8 @@ p5.prototype._onkeyup = function(e) {
  * function draw() {
  *   fill(value);
  *   rect(25, 25, 50, 50);
+ *   describe(`black rect center. turns white when 'a' key typed and
+ *     black when 'b' pressed`);
  * }
  * function keyTyped() {
  *   if (key === 'a') {
@@ -275,9 +271,6 @@ p5.prototype._onkeyup = function(e) {
  * }
  * </code>
  * </div>
- *
- * @alt
- * black rect center. turns white when 'a' key typed and black when 'b' pressed
  */
 p5.prototype._onkeypress = function(e) {
   if (e.which === this._lastKeyCodeTyped) {
@@ -345,6 +338,8 @@ p5.prototype._onblur = function(e) {
  *
  *   clear();
  *   ellipse(x, y, 50, 50);
+ *   describe(`50×50 red ellipse moves left, right, up, and
+ *     down with arrow presses.`);
  * }
  * </code></div>
  *
@@ -369,12 +364,10 @@ p5.prototype._onblur = function(e) {
  *   clear();
  *   fill(255, 0, 0);
  *   ellipse(50, 50, diameter, diameter);
+ *   describe(`50×50 red ellipse gets bigger or smaller when
+ *     + or - are pressed.`);
  * }
  * </code></div>
- *
- * @alt
- * 50×50 red ellipse moves left, right, up and down with arrow presses.
- * 50×50 red ellipse gets bigger or smaller when + or - are pressed.
  */
 p5.prototype.keyIsDown = function(code) {
   p5._validateParameters('keyIsDown', arguments);
diff --git a/src/events/mouse.js b/src/events/mouse.js
index ae449c3191..a8e3df0878 100644
--- a/src/events/mouse.js
+++ b/src/events/mouse.js
@@ -32,11 +32,11 @@ import * as constants from '../core/constants';
  *   background(237, 34, 93);
  *   fill(0);
  *   rect(x, 50, 50, 50);
+ *   describe(`box moves left and right according to mouse movement
+ *     then slowly back towards the center`);
  * }
  * </code>
  * </div>
- * @alt
- * box moves left and right according to mouse movement then slowly back towards the center
  */
 p5.prototype.movedX = 0;
 
@@ -62,11 +62,11 @@ p5.prototype.movedX = 0;
  *   background(237, 34, 93);
  *   fill(0);
  *   rect(y, 50, 50, 50);
+ *   describe(`box moves up and down according to mouse movement then
+ *     slowly back towards the center`);
  * }
  * </code>
  * </div>
- * @alt
- * box moves up and down according to mouse movement then slowly back towards the center
  */
 p5.prototype.movedY = 0;
 /*
@@ -94,12 +94,10 @@ p5.prototype._hasMouseInteracted = false;
  * function draw() {
  *   background(244, 248, 252);
  *   line(mouseX, 0, mouseX, 100);
+ *   describe(`horizontal black line moves left and right with mouse x-position`);
  * }
  * </code>
  * </div>
- *
- * @alt
- * horizontal black line moves left and right with mouse x-position
  */
 p5.prototype.mouseX = 0;
 
@@ -120,12 +118,10 @@ p5.prototype.mouseX = 0;
  * function draw() {
  *   background(244, 248, 252);
  *   line(0, mouseY, 100, mouseY);
+ *   describe(`vertical black line moves up and down with mouse y-position`);
  * }
  * </code>
  * </div>
- *
- * @alt
- * vertical black line moves up and down with mouse y-position
  */
 p5.prototype.mouseY = 0;
 
@@ -152,12 +148,11 @@ p5.prototype.mouseY = 0;
  *   background(244, 248, 252);
  *   line(mouseX, mouseY, pmouseX, pmouseY);
  *   print(pmouseX + ' -> ' + mouseX);
+ *   describe(`line trail is created from cursor movements.
+ *     faster movement make longer line.`);
  * }
  * </code>
  * </div>
- *
- * @alt
- * line trail is created from cursor movements. faster movement make longer line.
  */
 p5.prototype.pmouseX = 0;
 
@@ -183,12 +178,11 @@ p5.prototype.pmouseX = 0;
  *   }
  *
  *   print(pmouseY + ' -> ' + mouseY);
+ *   describe(`60×60 black rect center, fuchsia background.
+ *     rect flickers on mouse movement`);
  * }
  * </code>
  * </div>
- *
- * @alt
- * 60×60 black rect center, fuchsia background. rect flickers on mouse movement
  */
 p5.prototype.pmouseY = 0;
 
@@ -221,12 +215,11 @@ p5.prototype.pmouseY = 0;
  *
  *   //the y of the square is relative to the canvas
  *   rect(20, mouseY, 60, 60);
+ *   describe(`60×60 black rect y moves with mouse y and fuchsia
+ *     canvas moves with mouse x`);
  * }
  * </code>
  * </div>
- *
- * @alt
- * 60×60 black rect y moves with mouse y and fuchsia canvas moves with mouse x
  */
 p5.prototype.winMouseX = 0;
 
@@ -259,12 +252,11 @@ p5.prototype.winMouseX = 0;
  *
  *   //the x of the square is relative to the canvas
  *   rect(mouseX, 20, 60, 60);
+ *   describe(`60×60 black rect x moves with mouse x and
+ *     fuchsia canvas y moves with mouse y`);
  * }
  * </code>
  * </div>
- *
- * @alt
- * 60×60 black rect x moves with mouse x and fuchsia canvas y moves with mouse y
  */
 p5.prototype.winMouseY = 0;
 
@@ -299,12 +291,11 @@ p5.prototype.winMouseY = 0;
  *   ellipse(50, 50, 10 + speed * 5, 10 + speed * 5);
  *   //move the canvas to the mouse position
  *   myCanvas.position(winMouseX + 1, winMouseY + 1);
+ *   describe(`fuchsia ellipse moves with mouse x and y.
+ *     Grows and shrinks with mouse speed`);
  * }
  * </code>
  * </div>
- *
- * @alt
- * fuchsia ellipse moves with mouse x and y. Grows and shrinks with mouse speed
  */
 p5.prototype.pwinMouseX = 0;
 
@@ -339,12 +330,11 @@ p5.prototype.pwinMouseX = 0;
  *   ellipse(50, 50, 10 + speed * 5, 10 + speed * 5);
  *   //move the canvas to the mouse position
  *   myCanvas.position(winMouseX + 1, winMouseY + 1);
+ *   describe(`fuchsia ellipse moves with mouse x and y.
+ *     Grows and shrinks with mouse speed`);
  * }
  * </code>
  * </div>
- *
- * @alt
- * fuchsia ellipse moves with mouse x and y. Grows and shrinks with mouse speed
  */
 p5.prototype.pwinMouseY = 0;
 
@@ -377,12 +367,11 @@ p5.prototype.pwinMouseY = 0;
  *   }
  *
  *   print(mouseButton);
+ *   describe(`50×50 black ellipse appears on center of fuchsia
+ *     canvas on mouse click/press.`);
  * }
  * </code>
  * </div>
- *
- * @alt
- * 50×50 black ellipse appears on center of fuchsia canvas on mouse click/press.
  */
 p5.prototype.mouseButton = 0;
 
@@ -407,12 +396,11 @@ p5.prototype.mouseButton = 0;
  *   }
  *
  *   print(mouseIsPressed);
+ *   describe(`black 50×50 rect becomes ellipse with mouse click/press.
+ *     fuchsia background.`);
  * }
  * </code>
  * </div>
- *
- * @alt
- * black 50×50 rect becomes ellipse with mouse click/press. fuchsia background.
  */
 p5.prototype.mouseIsPressed = false;
 
@@ -497,6 +485,8 @@ p5.prototype._setMouseButton = function(e) {
  * function draw() {
  *   fill(value);
  *   rect(25, 25, 50, 50);
+ *   describe(`black 50×50 rect becomes lighter with mouse movements until
+ *   white then resets no image displayed`);
  * }
  * function mouseMoved() {
  *   value = value + 5;
@@ -526,10 +516,6 @@ p5.prototype._setMouseButton = function(e) {
  * }
  * </code>
  * </div>
- *
- * @alt
- * black 50×50 rect becomes lighter with mouse movements until white then resets
- * no image displayed
  */
 
 /**
@@ -552,6 +538,8 @@ p5.prototype._setMouseButton = function(e) {
  * function draw() {
  *   fill(value);
  *   rect(25, 25, 50, 50);
+ *   describe(`black 50×50 rect turns lighter with mouse click and
+ *     drag until white, resets`);
  * }
  * function mouseDragged() {
  *   value = value + 5;
@@ -581,10 +569,6 @@ p5.prototype._setMouseButton = function(e) {
  * }
  * </code>
  * </div>
- *
- * @alt
- * black 50×50 rect turns lighter with mouse click and drag until white, resets
- * no image displayed
  */
 p5.prototype._onmousemove = function(e) {
   const context = this._isGlobal ? window : this;
@@ -634,6 +618,7 @@ p5.prototype._onmousemove = function(e) {
  * function draw() {
  *   fill(value);
  *   rect(25, 25, 50, 50);
+ *   describe(`black 50×50 rect turns white with mouse click/press.`);
  * }
  * function mousePressed() {
  *   if (value === 0) {
@@ -664,10 +649,6 @@ p5.prototype._onmousemove = function(e) {
  * }
  * </code>
  * </div>
- *
- * @alt
- * black 50×50 rect turns white with mouse click/press.
- * no image displayed
  */
 p5.prototype._onmousedown = function(e) {
   const context = this._isGlobal ? window : this;
@@ -714,6 +695,7 @@ p5.prototype._onmousedown = function(e) {
  * function draw() {
  *   fill(value);
  *   rect(25, 25, 50, 50);
+ *   describe(`black 50×50 rect turns white with mouse click/press.`);
  * }
  * function mouseReleased() {
  *   if (value === 0) {
@@ -744,10 +726,6 @@ p5.prototype._onmousedown = function(e) {
  * }
  * </code>
  * </div>
- *
- * @alt
- * black 50×50 rect turns white with mouse click/press.
- * no image displayed
  */
 p5.prototype._onmouseup = function(e) {
   const context = this._isGlobal ? window : this;
@@ -792,6 +770,7 @@ p5.prototype._ondragover = p5.prototype._onmousemove;
  * function draw() {
  *   fill(value);
  *   rect(25, 25, 50, 50);
+ *   describe(`black 50×50 rect turns white with mouse click/press.`);
  * }
  *
  * function mouseClicked() {
@@ -823,10 +802,6 @@ p5.prototype._ondragover = p5.prototype._onmousemove;
  * }
  * </code>
  * </div>
- *
- * @alt
- * black 50×50 rect turns white with mouse click/press.
- * no image displayed
  */
 p5.prototype._onclick = function(e) {
   const context = this._isGlobal ? window : this;
@@ -860,6 +835,7 @@ p5.prototype._onclick = function(e) {
  * function draw() {
  *   fill(value);
  *   rect(25, 25, 50, 50);
+ *   describe(`black 50×50 rect turns white with mouse doubleClick/press.`);
  * }
  *
  * function doubleClicked() {
@@ -891,10 +867,6 @@ p5.prototype._onclick = function(e) {
  * }
  * </code>
  * </div>
- *
- * @alt
- * black 50×50 rect turns white with mouse doubleClick/press.
- * no image displayed
  */
 
 p5.prototype._ondblclick = function(e) {
@@ -949,6 +921,8 @@ p5.prototype._pmouseWheelDeltaY = 0;
  *   background(237, 34, 93);
  *   fill(0);
  *   rect(25, pos, 50, 50);
+ *   describe(`black 50×50 rect moves up and down with vertical scroll.
+ *     fuchsia background`);
  * }
  *
  * function mouseWheel(event) {
@@ -960,9 +934,6 @@ p5.prototype._pmouseWheelDeltaY = 0;
  * }
  * </code>
  * </div>
- *
- * @alt
- * black 50×50 rect moves up and down with vertical scroll. fuchsia background
  */
 p5.prototype._onwheel = function(e) {
   const context = this._isGlobal ? window : this;
@@ -1002,12 +973,11 @@ p5.prototype._onwheel = function(e) {
  *   cam.pan(-movedX * 0.001);
  *   cam.tilt(movedY * 0.001);
  *   sphere(25);
+ *   describe(`3D scene moves according to mouse mouse movement in a
+ *     first person perspective`);
  * }
  * </code>
  * </div>
- *
- * @alt
- * 3D scene moves according to mouse mouse movement in a first person perspective
  */
 p5.prototype.requestPointerLock = function() {
   // pointer lock object forking for cross browser
@@ -1036,6 +1006,7 @@ p5.prototype.requestPointerLock = function() {
  * let locked = false;
  * function draw() {
  *   background(237, 34, 93);
+ *   describe(`cursor gets locked / unlocked on mouse-click`);
  * }
  * function mouseClicked() {
  *   if (!locked) {
@@ -1048,9 +1019,6 @@ p5.prototype.requestPointerLock = function() {
  * }
  * </code>
  * </div>
- *
- * @alt
- * cursor gets locked / unlocked on mouse-click
  */
 p5.prototype.exitPointerLock = function() {
   document.exitPointerLock();
diff --git a/src/events/touch.js b/src/events/touch.js
index 4849dc5d13..bfda5e3a06 100644
--- a/src/events/touch.js
+++ b/src/events/touch.js
@@ -29,12 +29,11 @@ import p5 from '../core/main';
  *   clear();
  *   let display = touches.length + ' touches';
  *   text(display, 5, 10);
+ *   describe(`Number of touches currently registered are displayed
+ *     on the canvas`);
  * }
  * </code>
  * </div>
- *
- * @alt
- * Number of touches currently registered are displayed on the canvas
  */
 p5.prototype.touches = [];
 
@@ -88,6 +87,7 @@ function getTouchInfo(canvas, w, h, e, i = 0) {
  * function draw() {
  *   fill(value);
  *   rect(25, 25, 50, 50);
+ *   describe(`50×50 black rect turns white with touch event.`);
  * }
  * function touchStarted() {
  *   if (value === 0) {
@@ -106,6 +106,7 @@ function getTouchInfo(canvas, w, h, e, i = 0) {
  *   // prevent default
  *   return false;
  * }
+ * describe('no image displayed');
  * </code>
  * </div>
  *
@@ -116,12 +117,9 @@ function getTouchInfo(canvas, w, h, e, i = 0) {
  * function touchStarted(event) {
  *   console.log(event);
  * }
+ * describe('no image displayed');
  * </code>
  * </div>
- *
- * @alt
- * 50×50 black rect turns white with touch event.
- * no image displayed
  */
 p5.prototype._ontouchstart = function(e) {
   const context = this._isGlobal ? window : this;
@@ -168,6 +166,7 @@ p5.prototype._ontouchstart = function(e) {
  * function draw() {
  *   fill(value);
  *   rect(25, 25, 50, 50);
+ *   describe(`50×50 black rect turns lighter with touch until white. resets`);
  * }
  * function touchMoved() {
  *   value = value + 5;
@@ -185,6 +184,7 @@ p5.prototype._ontouchstart = function(e) {
  *   // prevent default
  *   return false;
  * }
+ * describe('no image displayed');
  * </code>
  * </div>
  *
@@ -195,12 +195,9 @@ p5.prototype._ontouchstart = function(e) {
  * function touchMoved(event) {
  *   console.log(event);
  * }
+ * describe('no image displayed');
  * </code>
  * </div>
- *
- * @alt
- * 50×50 black rect turns lighter with touch until white. resets
- * no image displayed
  */
 p5.prototype._ontouchmove = function(e) {
   const context = this._isGlobal ? window : this;
@@ -240,6 +237,7 @@ p5.prototype._ontouchmove = function(e) {
  * function draw() {
  *   fill(value);
  *   rect(25, 25, 50, 50);
+ *   describe(`50×50 black rect turns white with touch.`);
  * }
  * function touchEnded() {
  *   if (value === 0) {
@@ -258,6 +256,7 @@ p5.prototype._ontouchmove = function(e) {
  *   // prevent default
  *   return false;
  * }
+ * describe('no image displayed');
  * </code>
  * </div>
  *
@@ -268,12 +267,9 @@ p5.prototype._ontouchmove = function(e) {
  * function touchEnded(event) {
  *   console.log(event);
  * }
+ * describe('no image displayed');
  * </code>
  * </div>
- *
- * @alt
- * 50×50 black rect turns white with touch.
- * no image displayed
  */
 p5.prototype._ontouchend = function(e) {
   this._setProperty('mouseIsPressed', false);