docs(src/webgl): Use describe() instead of @alt

Addresses #5139

Author: Zearin

src/webgl/3d_primitives.js

@@ -33,18 +33,11 @@ import * as constants from '../core/constants';
  * function draw() {
  *   background(200);
  *   plane(50, 50);
+ *   describe(`A white plane (shaped like a square).
+ *     Black lines show that the plane is built from 2 triangles.`);
  * }
  * </code>
  * </div>
- *
- * @alt
- * Nothing displayed on canvas
- * Rotating interior view of a box with sides that change color.
- * 3d red and green gradient.
- * Rotating interior view of a cylinder with sides that change color.
- * Rotating view of a cylinder with sides that change color.
- * 3d red and green gradient.
- * rotating view of a multi-colored cylinder with concave sides.
  */
 p5.prototype.plane = function(width, height, detailX, detailY) {
   this._assert3d('plane');
@@ -121,6 +114,7 @@ p5.prototype.plane = function(width, height, detailX, detailY) {
  *   rotateX(frameCount * 0.01);
  *   rotateY(frameCount * 0.01);
  *   box(50);
+ *   describe(`Rotating view of a 3D box with sides of length 50.`);
  * }
  * </code>
  * </div>
@@ -239,6 +233,9 @@ p5.prototype.box = function(width, height, depth, detailX, detailY) {
  * function draw() {
  *   background(205, 102, 94);
  *   sphere(40);
+ *   describe(`A white sphere with a diameter of 40.
+ *     Black lines on its surface show how the sphere is built out of
+ *     many small triangles.`);
  * }
  * </code>
  * </div>
@@ -262,6 +259,14 @@ p5.prototype.box = function(width, height, depth, detailX, detailY) {
  *   background(205, 105, 94);
  *   rotateY(millis() / 1000);
  *   sphere(40, detailX.value(), 16);
+ *   describe(`A white rotating sphere-like shape with a diameter of 40.
+ *     Its actual shape is similar to a clam shell.
+ *     Black lines on its surface show how the sphere is built out of
+ *     many small triangles.
+ *     When adjusting the slider below the drawing, the shape increases
+ *     the number of small triangles making up the sphere, making the
+ *     final shape increasingly round as the slider approaches its
+ *     maximum setting.`);
  * }
  * </code>
  * </div>
@@ -285,6 +290,15 @@ p5.prototype.box = function(width, height, depth, detailX, detailY) {
  *   background(205, 105, 94);
  *   rotateY(millis() / 1000);
  *   sphere(40, 16, detailY.value());
+ *   describe(`A white rotating sphere-like shape with a diameter of 40.
+ *     Its actual shape is like a cylinder with the top and bottom
+ *     surface protruding outward.
+ *     Black lines on its surface show how the sphere is built out of
+ *     many small triangles.
+ *     When adjusting the slider below the drawing, the shape increases
+ *     the number of small triangles making up the sphere, making the
+ *     final shape increasingly round as the slider approaches its
+ *     maximum setting.`);
  * }
  * </code>
  * </div>
@@ -458,6 +472,9 @@ const _truncatedCone = function(
  *   rotateX(frameCount * 0.01);
  *   rotateZ(frameCount * 0.01);
  *   cylinder(20, 50);
+ *   describe(`A spinning view of a white cylinder.
+ *     Black lines on its surface show how the cylinder is built out of
+ *     many small triangles.`);
  * }
  * </code>
  * </div>
@@ -481,6 +498,11 @@ const _truncatedCone = function(
  *   background(205, 105, 94);
  *   rotateY(millis() / 1000);
  *   cylinder(20, 75, detailX.value(), 1);
+ *   describe(`A spinning view of what appears to be a white plane.
+ *     Black lines on its surface show how the shape is built out of
+ *     many small triangles.
+ *     As you increase the slider below the canvas, the shape gradually
+ *     becomes smoother and closer to a cylinder.`);
  * }
  * </code>
  * </div>
@@ -504,6 +526,12 @@ const _truncatedCone = function(
  *   background(205, 105, 94);
  *   rotateY(millis() / 1000);
  *   cylinder(20, 75, 16, detailY.value());
+ *   describe(`A spinning view of a white cylinder.
+ *     Black lines on its surface show how the shape is built out of
+ *     many small triangles.
+ *     As you increase the slider below the canvas, the shape increases
+ *     the number of triangles on the outer (round) surface, but the
+ *     smoothness of the shape remains the same.`);
  * }
  * </code>
  * </div>

src/webgl/interaction.js

@@ -39,12 +39,11 @@ import * as constants from '../core/constants';
  *   orbitControl();
  *   rotateY(0.5);
  *   box(30, 50);
+ *   describe(`Camera orbits around a box when mouse moved while
+ *     holding the button down.`);
  * }
  * </code>
  * </div>
- *
- * @alt
- * Camera orbits around a box when mouse is hold-clicked & then moved.
  */
 
 // implementation based on three.js 'orbitControls':
@@ -183,14 +182,14 @@ p5.prototype.orbitControl = function(sensitivityX, sensitivityY, sensitivityZ) {
  *   if (keyIsDown(32)) {
  *     noDebugMode();
  *   }
+ *   describe(`a 3D box is centered on a grid in a 3D sketch.
+ *     an icon indicates the direction of each axis:
+ *     a red line points +X, a green line +Y, and a blue line +Z.
+ *     the grid and icon disappear when the spacebar is pressed.`);
  * }
  * </code>
  * </div>
- * @alt
- * a 3D box is centered on a grid in a 3D sketch. an icon
- * indicates the direction of each axis: a red line points +X,
- * a green line +Y, and a blue line +Z. the grid and icon disappear when the
- * spacebar is pressed.
+ *
  *
  * @example
  * <div>
@@ -207,11 +206,10 @@ p5.prototype.orbitControl = function(sensitivityX, sensitivityY, sensitivityZ) {
  *   background(200);
  *   orbitControl();
  *   box(15, 30);
+ *   describe(`a 3D box is centered on a grid in a 3D sketch.`);
  * }
  * </code>
  * </div>
- * @alt
- * a 3D box is centered on a grid in a 3D sketch.
  *
  * @example
  * <div>
@@ -230,13 +228,12 @@ p5.prototype.orbitControl = function(sensitivityX, sensitivityY, sensitivityZ) {
  *   background(200);
  *   orbitControl();
  *   box(15, 30);
+ *   describe(`a 3D box is centered in a 3D sketch.
+ *     an icon indicates the direction of each axis:
+ *     a red line points +X, a green line +Y, and a blue line +Z.`);
  * }
  * </code>
  * </div>
- * @alt
- * a 3D box is centered in a 3D sketch. an icon
- * indicates the direction of each axis: a red line points +X,
- * a green line +Y, and a blue line +Z.
  *
  * @example
  * <div>
@@ -253,11 +250,10 @@ p5.prototype.orbitControl = function(sensitivityX, sensitivityY, sensitivityZ) {
  *   background(200);
  *   orbitControl();
  *   box(15, 30);
+ *   describe(`a 3D box is centered on a grid in a 3D sketch`);
  * }
  * </code>
  * </div>
- * @alt
- * a 3D box is centered on a grid in a 3D sketch
  *
  * @example
  * <div>
@@ -280,13 +276,12 @@ p5.prototype.orbitControl = function(sensitivityX, sensitivityY, sensitivityZ) {
  *   // set the stroke color and weight for the grid!
  *   stroke(255, 0, 150);
  *   strokeWeight(0.8);
+ *   describe(`a 3D box is centered on a grid in a 3D sketch.
+ *     an icon indicates the direction of each axis:
+ *     a red line points +X, a green line +Y, and a blue line +Z.`);
  * }
  * </code>
  * </div>
- * @alt
- * a 3D box is centered on a grid in a 3D sketch. an icon
- * indicates the direction of each axis: a red line points +X,
- * a green line +Y, and a blue line +Z.
  */
 
 /**
@@ -388,14 +383,13 @@ p5.prototype.debugMode = function(...args) {
  *   if (keyIsDown(32)) {
  *     noDebugMode();
  *   }
+ *   describe(`a 3D box is centered on a grid in a 3D sketch.
+ *     an icon indicates the direction of each axis:
+ *     a red line points +X, a green line +Y, and a blue line +Z.
+ *     the grid and icon disappear when the spacebar is pressed.`);
  * }
  * </code>
  * </div>
- * @alt
- * a 3D box is centered on a grid in a 3D sketch. an icon
- * indicates the direction of each axis: a red line points +X,
- * a green line +Y, and a blue line +Z. the grid and icon disappear when the
- * spacebar is pressed.
  */
 p5.prototype.noDebugMode = function() {
   this._assert3d('noDebugMode');

src/webgl/light.js

@@ -47,8 +47,6 @@ import * as constants from '../core/constants';
  * }
  * </code>
  * </div>
- * @alt
- * sphere with coral color under black light
  *
  * @example
  * <div>
@@ -66,8 +64,6 @@ import * as constants from '../core/constants';
  * }
  * </code>
  * </div>
- * @alt
- * sphere with coral color under white light
  */
 
 /**
@@ -147,7 +143,9 @@ p5.prototype.ambientLight = function(v1, v2, v3, a) {
  *   createCanvas(100, 100, WEBGL);
  *   noStroke();
  *   describe(
- *     'Sphere with specular highlight. Clicking the mouse toggles the specular highlight color between red and the default white.'
+ *     `Sphere with specular highlight.
+ *      Clicking the mouse toggles the specular highlight color between
+ *      red and the default white.`
  *   );
  * }
  *
@@ -180,9 +178,6 @@ p5.prototype.ambientLight = function(v1, v2, v3, a) {
  * </code>
  * </div>
  *
- * @alt
- * Sphere with specular highlight. Clicking the mouse toggles the
- * specular highlight color between red and the default white.
  */
 
 /**
@@ -262,7 +257,8 @@ p5.prototype.specularColor = function(v1, v2, v3) {
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
  *   describe(
- *     'scene with sphere and directional light. The direction of the light is controlled with the mouse position.'
+ *     `Scene with sphere and directional light. The direction of
+ *      the light is controlled with the mouse position.`
  *   );
  * }
  * function draw() {
@@ -276,10 +272,6 @@ p5.prototype.specularColor = function(v1, v2, v3) {
  * }
  * </code>
  * </div>
- *
- * @alt
- * scene with sphere and directional light. The direction of
- * the light is controlled with the mouse position.
  */
 
 /**
@@ -383,7 +375,8 @@ p5.prototype.directionalLight = function(v1, v2, v3, x, y, z) {
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
  *   describe(
- *     'scene with sphere and point light. The position of the light is controlled with the mouse position.'
+ *     `Scene with sphere and point light. The position of
+ *      the light is controlled with the mouse position.`
  *   );
  * }
  * function draw() {
@@ -404,10 +397,6 @@ p5.prototype.directionalLight = function(v1, v2, v3, x, y, z) {
  * }
  * </code>
  * </div>
- *
- * @alt
- * scene with sphere and point light. The position of
- * the light is controlled with the mouse position.
  */
 
 /**
@@ -492,7 +481,7 @@ p5.prototype.pointLight = function(v1, v2, v3, x, y, z) {
  * <code>
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
- *   describe('the light is partially ambient and partially directional');
+ *   describe('The light is partially ambient and partially directional');
  * }
  * function draw() {
  *   background(0);
@@ -504,9 +493,6 @@ p5.prototype.pointLight = function(v1, v2, v3, x, y, z) {
  * }
  * </code>
  * </div>
- *
- * @alt
- * the light is partially ambient and partially directional
  */
 p5.prototype.lights = function() {
   this._assert3d('lights');
@@ -547,7 +533,7 @@ p5.prototype.lights = function() {
  *   createCanvas(100, 100, WEBGL);
  *   noStroke();
  *   describe(
- *     'Two spheres with different falloff values show different intensity of light'
+ *     'Two spheres with different falloff values show different intensities of light'
  *   );
  * }
  * function draw() {
@@ -574,9 +560,6 @@ p5.prototype.lights = function() {
  * }
  * </code>
  * </div>
- *
- * @alt
- * Two spheres with different falloff values show different intensity of light
  */
 p5.prototype.lightFalloff = function(
   constantAttenuation,
@@ -670,7 +653,8 @@ p5.prototype.lightFalloff = function(
  * function setup() {
  *   createCanvas(100, 100, WEBGL);
  *   describe(
- *     'scene with sphere and spot light. The position of the light is controlled with the mouse position.'
+ *     `Scene with sphere and spot light.
+ *      The position of the light is controlled with the mouse position.`
  *   );
  * }
  * function draw() {
@@ -692,10 +676,6 @@ p5.prototype.lightFalloff = function(
  * }
  * </code>
  * </div>
- *
- * @alt
- * scene with sphere and spot light. The position of
- * the light is controlled with the mouse position.
  */
 /**
  * @method spotLight
@@ -1028,10 +1008,6 @@ p5.prototype.spotLight = function(
  * }
  * </code>
  * </div>
- *
- * @alt
- * Three white spheres. Each appears as a different
- * color due to lighting.
  */
 p5.prototype.noLights = function() {
   this._assert3d('noLights');