From 861cf746a08c287e7e36ea66b46680b9754d967c Mon Sep 17 00:00:00 2001 From: Zearin Date: Sun, 6 Feb 2022 13:54:02 -0500 Subject: [PATCH] docs(src/math): Use `describe()` instead of `@alt` Addresses #5139 --- src/math/calculation.js | 111 +++++++++++++++++++-------------------- src/math/math.js | 4 +- src/math/noise.js | 17 +++--- src/math/p5.Vector.js | 6 +-- src/math/random.js | 22 ++++---- src/math/trigonometry.js | 24 ++++----- 6 files changed, 84 insertions(+), 100 deletions(-) diff --git a/src/math/calculation.js b/src/math/calculation.js index 7bc94ea85b..80a30d265e 100644 --- a/src/math/calculation.js +++ b/src/math/calculation.js @@ -22,11 +22,10 @@ import p5 from '../core/main'; * * print(x); // -3 * print(y); // 3 + * + * describe(`no image displayed`); * } * - * - * @alt - * no image displayed */ p5.prototype.abs = Math.abs; @@ -61,11 +60,11 @@ p5.prototype.abs = Math.abs; * noStroke(); * text(nfc(ax, 2), ax, ay - 5); * text(nfc(bx, 1), bx, by - 5); + * + * describe(`2 horizontal lines & number sets. increase with + * mouse x. bottom to 2 decimals`); * } * - * - * @alt - * 2 horizontal lines & number sets. increase with mouse x. bottom to 2 decimals */ p5.prototype.ceil = Math.ceil; @@ -102,11 +101,11 @@ p5.prototype.ceil = Math.ceil; * ellipse(xm, 33, 9, 9); // Not Constrained * fill(0); * ellipse(xc, 66, 9, 9); // Constrained + * + * describe(`2 vertical lines. 2 ellipses move with mouse X, + * 1 does not move past lines`); * } * - * - * @alt - * 2 vertical lines. 2 ellipses move with mouse X 1 does not move passed lines */ p5.prototype.constrain = function(n, low, high) { p5._validateParameters('constrain', arguments); @@ -152,11 +151,11 @@ p5.prototype.constrain = function(n, low, high) { * text(nfc(d, 1), 0, -5); * pop(); * // Fancy! + * + * describe(`2 ellipses joined by line. 1 ellipse moves with + * mouse X&Y. Distance displayed.`); * } * - * - * @alt - * 2 ellipses joined by line. 1 ellipse moves with mouse X&Y. Distance displayed. */ /** * @method dist @@ -220,11 +219,10 @@ p5.prototype.dist = function(...args) { * endShape(); * line(0, 0, 0, height); * line(0, height - 1, width, height - 1); + * + * describe(`ellipse moves along a curve with mouse x. e^n displayed.`); * } * - * - * @alt - * ellipse moves along a curve with mouse x. e^n displayed. */ p5.prototype.exp = Math.exp; @@ -258,11 +256,11 @@ p5.prototype.exp = Math.exp; * noStroke(); * text(nfc(ax, 2), ax, ay - 5); * text(nfc(bx, 1), bx, by - 5); + * + * describe(`2 horizontal lines & number sets. + * increase with mouse x. bottom to 2 decimals`); * } * - * - * @alt - * 2 horizontal lines & number sets. increase with mouse x. bottom to 2 decimals */ p5.prototype.floor = Math.floor; @@ -302,11 +300,11 @@ p5.prototype.floor = Math.floor; * point(c, y); * point(d, y); * point(e, y); + * + * describe(`5 points horizontally staggered mid-canvas. + * mid 3 are grey, outer black`); * } * - * - * @alt - * 5 points horizontally staggered mid-canvas. mid 3 are grey, outer black */ p5.prototype.lerp = function(start, stop, amt) { p5._validateParameters('lerp', arguments); @@ -360,11 +358,11 @@ p5.prototype.lerp = function(start, stop, amt) { * endShape(); * line(0, 0, 0, height); * line(0, height / 2, width, height / 2); + * + * describe(`ellipse moves along a curve with mouse x. + * natural logarithm of n displayed.`); * } * - * - * @alt - * ellipse moves along a curve with mouse x. natural logarithm of n displayed. */ p5.prototype.log = Math.log; @@ -395,11 +393,10 @@ p5.prototype.log = Math.log; * print(mag(x1, y2)); // Prints "72.80109889280519" * line(0, 0, x2, y2); * print(mag(x2, y2)); // Prints "106.3014581273465" + * + * describe(`4 lines of different length radiate from top left of canvas.`); * } * - * - * @alt - * 4 lines of different length radiate from top left of canvas. */ p5.prototype.mag = function(x, y) { p5._validateParameters('mag', arguments); @@ -426,6 +423,7 @@ p5.prototype.mag = function(x, y) { * let value = 25; * let m = map(value, 0, 100, 0, width); * ellipse(m, 50, 10, 10); + * describe(`10×10 white ellipse with in mid left canvas`); * *
@@ -441,12 +439,11 @@ p5.prototype.mag = function(x, y) { * //after setting withinBounds to true * let x2 = map(mouseX, 0, width, 0, 100, true); * ellipse(x2, 75, 25, 25); + * + * describe(`Two 25×25 white ellipses move with mouse x. + * Bottom has more range from X`); * }
- * - * @alt - * 10 by 10 white ellipse with in mid left canvas - * 2 25 by 25 white ellipses move with mouse x. Bottom has more range from X */ p5.prototype.map = function(n, start1, stop1, start2, stop2, withinBounds) { p5._validateParameters('map', arguments); @@ -490,11 +487,11 @@ p5.prototype.map = function(n, start1, stop1, start2, stop2, withinBounds) { * // Draw the Maximum value in the array. * textSize(32); * text(max(numArray), maxX, maxY); + * + * describe(`Small text at top reads: Array Elements 2 1 5 4 8 9. + * Large text at center: 9`); * } * - * - * @alt - * Small text at top reads: Array Elements 2 1 5 4 8 9. Large text at center: 9 */ /** * @method max @@ -538,11 +535,11 @@ p5.prototype.max = function(...args) { * // Draw the Minimum value in the array. * textSize(32); * text(min(numArray), maxX, maxY); + * + * describe(`Small text at top reads: Array Elements 2 1 5 4 8 9. + * Large text at center: 1`); * } * - * - * @alt - * Small text at top reads: Array Elements 2 1 5 4 8 9. Large text at center: 1 */ /** * @method min @@ -598,11 +595,11 @@ p5.prototype.min = function(...args) { * let normalY = 40; * let normalX = 20; * text(normalized, normalX, normalY); + * + * describe(`ellipse moves with mouse. 0 shown left, 100 right, + * and updating values center`); * } * - * - * @alt - * ellipse moves with mouse. 0 shown left & 100 right and updating values center */ p5.prototype.norm = function(n, start, stop) { p5._validateParameters('norm', arguments); @@ -635,11 +632,10 @@ p5.prototype.norm = function(n, start, stop) { * ellipse(eLoc * 4, eLoc * 4, pow(eSize, 3), pow(eSize, 3)); * * ellipse(eLoc * 8, eLoc * 8, pow(eSize, 4), pow(eSize, 4)); + * + * describe(`small to large ellipses radiating from top left of canvas`); * } * - * - * @alt - * small to large ellipses radiating from top left of canvas */ p5.prototype.pow = Math.pow; @@ -655,10 +651,12 @@ p5.prototype.pow = Math.pow; *
* let x = round(3.7); * text(x, width / 2, height / 2); + * describe(`"4" written in middle of canvas`); *
*
* let x = round(12.782383, 2); * text(x, width / 2, height / 2); + * describe(`"12.78" written in middle of canvas`); *
*
* function draw() { @@ -682,13 +680,10 @@ p5.prototype.pow = Math.pow; * noStroke(); * text(nfc(ax, 2), ax, ay - 5); * text(nfc(bx, 1), bx, by - 5); + * + * describe(`two horizontal lines rounded values displayed on top.`); * } *
- * - * @alt - * "4" written in middle of canvas - * "12.78" written in middle of canvas - * two horizontal lines rounded values displayed on top. */ p5.prototype.round = function(n, decimals) { if (!decimals) { @@ -734,11 +729,11 @@ p5.prototype.round = function(n, decimals) { * fill(0); * text('x = ' + x1, 0, y1 + spacing); * text('sq(x) = ' + x2, 0, y2 + spacing); + * + * describe(`horizontal center line squared values displayed on + * top and regular on bottom.`); * } * - * - * @alt - * horizontal center line squared values displayed on top and regular on bottom. */ p5.prototype.sq = n => n * n; @@ -779,11 +774,11 @@ p5.prototype.sq = n => n * n; * let spacing = 15; * text('x = ' + x1, 0, y1 + spacing); * text('sqrt(x) = ' + x2, 0, y2 + spacing); + * + * describe(`horizontal center line squareroot values displayed on + * top and regular on bottom.`); * } * - * - * @alt - * horizontal center line squareroot values displayed on top and regular on bottom. */ p5.prototype.sqrt = Math.sqrt; @@ -839,16 +834,16 @@ function hypot(x, y, z) { *
* text(7345.73472742, 10, 25); * text(fract(7345.73472742), 10, 75); + * describe(`first row having a number and the second having + * the fractional part of the number`); *
* *
* text(1.4215e-15, 10, 25); * text(fract(1.4215e-15), 10, 75); + * describe(`first row having a number expressed in scientific + * notation and the second having the fractional part of the number`); *
- * - * @alt - * first row having a number and the second having the fractional part of the number - * first row having a number expressed in scientific notation and the second having the fractional part of the number */ p5.prototype.fract = function(toConvert) { p5._validateParameters('fract', arguments); diff --git a/src/math/math.js b/src/math/math.js index 89d07aaeef..f8b9e475b3 100644 --- a/src/math/math.js +++ b/src/math/math.js @@ -30,11 +30,9 @@ import p5 from '../core/main'; * function draw() { * background(255); * line(v1.x, v1.y, mouseX, mouseY); + * describe(`draws a line from center of canvas to mouse pointer position.`); * } * - * - * @alt - * draws a line from center of canvas to mouse pointer position. */ p5.prototype.createVector = function(x, y, z) { if (this instanceof p5) { diff --git a/src/math/noise.js b/src/math/noise.js index cb58e0744d..44e44a48fc 100644 --- a/src/math/noise.js +++ b/src/math/noise.js @@ -76,6 +76,8 @@ let perlin; // will be initialized lazily by noise() or noiseSeed() * xoff = xoff + 0.01; * let n = noise(xoff) * width; * line(n, 0, n, height); + * describe(`vertical line moves left to right with updating + * noise values.`); * } * * @@ -89,13 +91,11 @@ let perlin; // will be initialized lazily by noise() or noiseSeed() * stroke(noiseVal*255); * line(x, mouseY+noiseVal*80, x, height); * } + * describe(`horizontal wave pattern effected by mouse x-position + * & updating noise values.`); * } * * - * - * @alt - * vertical line moves left to right with updating noise values. - * horizontal wave pattern effected by mouse x-position & updating noise values. */ p5.prototype.noise = function(x, y = 0, z = 0) { @@ -224,12 +224,11 @@ p5.prototype.noise = function(x, y = 0, z = 0) { * point(x + width / 2, y); * } * } + * describe(`2 vertical grey smokey patterns affected by + * mouse x-position and noise.`); * } * * - * - * @alt - * 2 vertical grey smokey patterns affected my mouse x-position and noise. */ p5.prototype.noiseDetail = function(lod, falloff) { if (lod > 0) { @@ -261,12 +260,10 @@ p5.prototype.noiseDetail = function(lod, falloff) { * xoff = xoff + .01; * let n = noise(xoff) * width; * line(n, 0, n, height); + * describe(`vertical grey lines drawing in pattern affected by noise.`); * } * * - * - * @alt - * vertical grey lines drawing in pattern affected by noise. */ p5.prototype.noiseSeed = function(seed) { // Linear Congruential Generator diff --git a/src/math/p5.Vector.js b/src/math/p5.Vector.js index fd0879cfc3..6469580d59 100644 --- a/src/math/p5.Vector.js +++ b/src/math/p5.Vector.js @@ -41,11 +41,11 @@ import * as constants from '../core/constants'; * ellipse(v2.x, v2.y, 50, 50); * v1.add(v2); * ellipse(v1.x, v1.y, 50, 50); + * + * describe(`2 white ellipses. One center-left the other + * bottom right and off canvas`); * * - * - * @alt - * 2 white ellipses. One center-left the other bottom right and off canvas */ p5.Vector = function Vector() { let x, y, z; diff --git a/src/math/random.js b/src/math/random.js index 2914020d33..6f37be8d5b 100644 --- a/src/math/random.js +++ b/src/math/random.js @@ -52,11 +52,9 @@ p5.prototype._lcgSetSeed = function(stateProperty, val) { * stroke(r); * line(i, 0, i, 100); * } + * describe(`many vertical lines drawn in white, black, or grey.`); * * - * - * @alt - * many vertical lines drawn in white, black or grey. */ p5.prototype.randomSeed = function(seed) { this._lcgSetSeed(randomStateProp, seed); @@ -92,6 +90,8 @@ p5.prototype.randomSeed = function(seed) { * stroke(r * 5); * line(50, i, 50 + r, i); * } + * describe(`100 horizontal lines from center canvas to right. + * The size and fill change each time.`); * * *
@@ -100,6 +100,8 @@ p5.prototype.randomSeed = function(seed) { * let r = random(-50, 50); * line(50, i, 50 + r, i); * } + * describe(`100 horizontal lines from center of canvas. + * The height & side change each render.`); * *
*
@@ -108,13 +110,9 @@ p5.prototype.randomSeed = function(seed) { * let words = ['apple', 'bear', 'cat', 'dog']; * let word = random(words); // select random word * text(word, 10, 50); // draw the word + * describe(`word displayed at random. Either apple, bear, cat, or dog.`); * *
- * - * @alt - * 100 horizontal lines from center canvas to right. size+fill change each time - * 100 horizontal lines from center of canvas. height & side change each render - * word displayed at random. Either apple, bear, cat, or dog */ /** * @method random @@ -175,6 +173,8 @@ p5.prototype.random = function(min, max) { * let x = randomGaussian(50, 15); * line(50, y, x, y); * } + * describe(`100 horizontal lines from center of canvas. + * The height & side change each render.`); * * *
@@ -199,12 +199,12 @@ p5.prototype.random = function(min, max) { * let dist = abs(distribution[i]); * line(0, 0, dist, 0); * } + * + * describe(`black lines radiate from center of canvas. + * The size changes each render.`); * } * *
- * @alt - * 100 horizontal lines from center of canvas. height & side change each render - * black lines radiate from center of canvas. size determined each render */ p5.prototype.randomGaussian = function(mean, sd = 1) { let y1, x1, x2, w; diff --git a/src/math/trigonometry.js b/src/math/trigonometry.js index d71449cfc2..40aa19a31b 100644 --- a/src/math/trigonometry.js +++ b/src/math/trigonometry.js @@ -145,12 +145,10 @@ p5.prototype.atan = function(ratio) { * let a = atan2(mouseY - height / 2, mouseX - width / 2); * rotate(a); * rect(-30, -5, 60, 10); + * describe(`60×10 rect at center of canvas rotates with mouse movements`); * } * * - * - * @alt - * 60 by 10 rect at center of canvas rotates with mouse movements */ p5.prototype.atan2 = function(y, x) { return this._fromRadians(Math.atan2(y, x)); @@ -173,11 +171,10 @@ p5.prototype.atan2 = function(y, x) { * line(i * 4, 50, i * 4, 50 + cos(a) * 40.0); * a = a + inc; * } + * describe(`vertical black lines form wave patterns, extend-down on + * left and right side`); * * - * - * @alt - * vertical black lines form wave patterns, extend-down on left and right side */ p5.prototype.cos = function(angle) { return Math.cos(this._toRadians(angle)); @@ -200,11 +197,10 @@ p5.prototype.cos = function(angle) { * line(i * 4, 50, i * 4, 50 + sin(a) * 40.0); * a = a + inc; * } + * describe(`vertical black lines extend down and up from center + * to form wave pattern.`); * * - * - * @alt - * vertical black lines extend down and up from center to form wave pattern */ p5.prototype.sin = function(angle) { return Math.sin(this._toRadians(angle)); @@ -227,10 +223,9 @@ p5.prototype.sin = function(angle) { * line(i, 50, i, 50 + tan(a) * 2.0); * a = a + inc; * } + * describe(`vertical black lines end down and up from center to + * form spike pattern.`); * - * - * @alt - * vertical black lines end down and up from center to form spike pattern */ p5.prototype.tan = function(angle) { return Math.tan(this._toRadians(angle)); @@ -303,13 +298,12 @@ p5.prototype.radians = angle => angle * constants.DEG_TO_RAD; * angleMode(RADIANS); // Change the mode to RADIANS * rotate(a); // variable a stays the same * rect(-40, -5, 20, 10); // Smaller rectangle is rotating in radians + * describe(`40×10 rect in center rotates with mouse moves. + * 20×10 rect moves faster.`); * } * * * - * @alt - * 40 by 10 rect in center rotates with mouse moves. 20 by 10 rect moves faster. - * */ p5.prototype.angleMode = function(mode) { if (mode === constants.DEGREES || mode === constants.RADIANS) {