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

Addresses #5139

Author: Zearin

src/webgl/3d_primitives.js

@@ -32,18 +32,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');
@@ -119,6 +112,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>
@@ -236,6 +230,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>
@@ -256,6 +253,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>
@@ -276,6 +281,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>
@@ -448,6 +462,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>
@@ -468,6 +485,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>
@@ -488,6 +510,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>
@@ -1245,7 +1273,7 @@ p5.RendererGL.prototype.quad = function(x1, y1, z1, x2, y2, z2, x3, y3, z3, x4,
 
   const gId =
     `quad|${x1}|${y1}|${z1}|${x2}|${y2}|${z2}|${x3}|${y3}|${z3}|${x4}|${y4}|${z4}|${detailX}|${detailY}`;
-  
+
   if (!this.geometryInHash(gId)) {
     const quadGeom = new p5.Geometry(detailX, detailY, function() {
       //algorithm adapted from c++ to js
@@ -1273,7 +1301,7 @@ p5.RendererGL.prototype.quad = function(x1, y1, z1, x2, y2, z2, x3, y3, z3, x4,
         }
       }
     });
-    
+
     quadGeom.faces = [];
     for(let y = 0; y < detailY-1; y++){
       for(let x = 0; x < detailX-1; x++){

src/webgl/interaction.js

@@ -36,12 +36,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':
@@ -177,14 +176,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>
@@ -200,11 +199,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>
@@ -220,13 +218,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>
@@ -242,11 +239,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>
@@ -266,13 +262,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.
  */
 
 /**
@@ -371,14 +366,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

@@ -28,6 +28,7 @@ import * as constants from '../core/constants';
  * ambientLight(0);
  * ambientMaterial(250);
  * sphere(40);
+ * describe(`evenly distributed light across a sphere`);
  * </code>
  * </div>
  * <div>
@@ -40,12 +41,10 @@ import * as constants from '../core/constants';
  *   ambientLight(100); // white light
  *   ambientMaterial(255, 102, 94); // magenta material
  *   box(30);
+ *   describe(`evenly distributed light across a rotating sphere`);
  * }
  * </code>
  * </div>
- * @alt
- * evenly distributed light across a sphere
- * evenly distributed light across a rotating sphere
  */
 
 /**
@@ -128,12 +127,10 @@ p5.prototype.ambientLight = function(v1, v2, v3, a) {
  *   pointLight(0, 255, 0, 0, 50, 50);
  *   specularMaterial(255);
  *   sphere(40);
+ *   describe(`different specular light sources from top and bottom of canvas`);
  * }
  * </code>
  * </div>
- *
- * @alt
- * different specular light sources from top and bottom of canvas
  */
 
 /**
@@ -199,12 +196,10 @@ p5.prototype.specularColor = function(v1, v2, v3) {
  *   directionalLight(250, 250, 250, -dirX, -dirY, -1);
  *   noStroke();
  *   sphere(40);
+ *   describe(`light source on canvas changeable with mouse position`);
  * }
  * </code>
  * </div>
- *
- * @alt
- * light source on canvas changeable with mouse position
  */
 
 /**
@@ -311,12 +306,10 @@ p5.prototype.directionalLight = function(v1, v2, v3, x, y, z) {
  *   pointLight(250, 250, 250, locX, locY, 50);
  *   noStroke();
  *   sphere(40);
+ *   describe(`spotlight on canvas changes position with mouse`);
  * }
  * </code>
  * </div>
- *
- * @alt
- * spot light on canvas changes position with mouse
  */
 
 /**
@@ -401,12 +394,10 @@ p5.prototype.pointLight = function(v1, v2, v3, x, y, z) {
  *   rotateY(millis() / 1000);
  *   rotateZ(millis() / 1000);
  *   box();
+ *   describe(`the light is partially ambient and partially directional`);
  * }
  * </code>
  * </div>
- *
- * @alt
- * the light is partially ambient and partially directional
  */
 p5.prototype.lights = function() {
   this._assert3d('lights');
@@ -463,12 +454,12 @@ p5.prototype.lights = function() {
  *   pointLight(250, 250, 250, locX + 25, locY, 50);
  *   sphere(20);
  *   pop();
+ *
+ *   describe(`Two spheres with different falloff values show
+ *     different intensity of light`);
  * }
  * </code>
  * </div>
- *
- * @alt
- * Two spheres with different falloff values show different intensity of light
  */
 p5.prototype.lightFalloff = function(
   constantAttenuation,
@@ -561,12 +552,11 @@ p5.prototype.lightFalloff = function(
  *   spotLight(0, 250, 0, locX, locY, 100, 0, 0, -1, Math.PI / 16);
  *   noStroke();
  *   sphere(40);
+ *
+ *   describe(`Spotlight on a sphere which changes position with mouse`);
  * }
  * </code>
  * </div>
- *
- * @alt
- * Spot light on a sphere which changes position with mouse
  */
 /**
  * @method spotLight
@@ -887,13 +877,12 @@ p5.prototype.spotLight = function(
  *   translate(30, 0, 0);
  *   ambientMaterial(255);
  *   sphere(13);
+ *
+ *   describe(`Three white spheres. Each appears as a different
+ *    color due to lighting.`);
  * }
  * </code>
  * </div>
- *
- * @alt
- * Three white spheres. Each appears as a different
- * color due to lighting.
  */
 p5.prototype.noLights = function() {
   this._assert3d('noLights');