Merge pull request #8031 from perminder-17/splineDocs

A few documentation issues to fix

Author: perminder-17

src/shape/curves.js

@@ -12,7 +12,7 @@ function curves(p5, fn){
    * Bézier curves can form shapes and curves that slope gently. They're defined
    * by two anchor points and two control points. Bézier curves provide more
    * control than the spline curves created with the
-   * <a href="#/p5/curve">curve()</a> function.
+   * <a href="#/p5/spline">spline()</a> function.
    *
    * The first two parameters, `x1` and `y1`, set the first anchor point. The
    * first anchor point is where the curve starts.
@@ -462,63 +462,81 @@ function curves(p5, fn){
 
   /**
    * Draws a curve using a Catmull-Rom spline.
-   *
+   * 
    * Spline curves can form shapes and curves that slope gently. They’re like
-   * cables that are attached to a set of points. Splines are defined by two
-   * anchor points and two control points.
-   *
-   * The first two parameters, `x1` and `y1`, set the first control point. This
-   * point isn’t drawn and can be thought of as the curve’s starting point.
-   *
-   * The next four parameters, `x2`, `y2`, `x3`, and `y3`, set the two anchor
-   * points. The anchor points are the start and end points of the curve’s
-   * visible segment.
-   *
-   * The seventh and eighth parameters, `x4` and `y4`, set the last control
-   * point. This point isn’t drawn and can be thought of as the curve’s ending
-   * point.
+   * cables that are attached to a set of points. By default (`ends: INCLUDE`),
+   * the curve passes through all four points you provide, in order
+   * `p0(x1,y1)` -> `p1(x2,y2)` -> `p2(x3,y3)` -> `p3(x4,y4)`. Think of them as 
+   * points on a curve. If you switch to `ends: EXCLUDE`, p0 and p3 act
+   * like control points and only the middle span `p1->p2` is drawn.
    *
    * Spline curves can also be drawn in 3D using WebGL mode. The 3D version of
    * `spline()` has twelve arguments because each point has x-, y-, and
    * z-coordinates.
    *
    * @method spline
-   * @param  {Number} x1 x-coordinate of the first control point.
-   * @param  {Number} y1 y-coordinate of the first control point.
-   * @param  {Number} x2 x-coordinate of the first anchor point.
-   * @param  {Number} y2 y-coordinate of the first anchor point.
-   * @param  {Number} x3 x-coordinate of the second anchor point.
-   * @param  {Number} y3 y-coordinate of the second anchor point.
-   * @param  {Number} x4 x-coordinate of the second control point.
-   * @param  {Number} y4 y-coordinate of the second control point.
+   * @param  {Number} x1 x-coordinate of point p0.
+   * @param  {Number} y1 y-coordinate of point p0.
+   * @param  {Number} x2 x-coordinate of point p1.
+   * @param  {Number} y2 y-coordinate of point p1.
+   * @param  {Number} x3 x-coordinate of point p2.
+   * @param  {Number} y3 y-coordinate of point p2.
+   * @param  {Number} x4 x-coordinate of point p3.
+   * @param  {Number} y4 y-coordinate of point p3.
    * @chainable
    *
    * @example
+   * 
+   * <div>
+   * <code>
+   * function setup() {
+   *   createCanvas(200, 200);
+   *   background(240);
+   *   noFill();
+   *
+   *   stroke(0);
+   *   strokeWeight(2);
+   *   spline(40, 60, 100, 40, 120, 120, 60, 140);
+   *
+   *   strokeWeight(5);
+   *   point(40, 60);
+   *   point(100, 40);
+   *   point(120, 120);
+   *   point(60, 140);
+   *
+   *   describe('A black spline passes smoothly through four points');
+   * }
+   * </code>
+   * </div>
+   * 
    * <div>
    * <code>
    * function setup() {
    *   createCanvas(100, 100);
    *
    *   background(200);
    *
+   *   // Exclude the ends—skip the outer spans (p0→p1 and p2→p3) so only the middle span (p1→p2) is drawn.
+   *   splineProperty('ends', EXCLUDE);
+   * 
    *   // Draw a black spline curve.
    *   noFill();
    *   strokeWeight(1);
    *   stroke(0);
    *   spline(5, 26, 73, 24, 73, 61, 15, 65);
    *
-   *   // Draw red spline curves from the anchor points to the control points.
+   *   // Draw red spline curves from the points.
    *   stroke(255, 0, 0);
    *   spline(5, 26, 5, 26, 73, 24, 73, 61);
    *   spline(73, 24, 73, 61, 15, 65, 15, 65);
    *
-   *   // Draw the anchor points in black.
+   *   // Draw the points in black.
    *   strokeWeight(5);
    *   stroke(0);
    *   point(73, 24);
    *   point(73, 61);
    *
-   *   // Draw the control points in red.
+   *   // Draw the points in red.
    *   stroke(255, 0, 0);
    *   point(5, 26);
    *   point(15, 65);
@@ -546,14 +564,17 @@ function curves(p5, fn){
    *
    * function draw() {
    *   background(200);
-   *
+   * 
+   *   // Exclude the ends—skip the outer spans (p0→p1 and p2→p3) so only the middle span (p1→p2) is drawn.
+   *   splineProperty('ends', EXCLUDE);
+   * 
    *   // Draw a black spline curve.
    *   noFill();
    *   strokeWeight(1);
    *   stroke(0);
    *   spline(x1, y1, 73, 24, 73, 61, 15, 65);
    *
-   *   // Draw red spline curves from the anchor points to the control points.
+   *   // Draw red spline curves from the points.
    *   stroke(255, 0, 0);
    *   spline(x1, y1, x1, y1, 73, 24, 73, 61);
    *   spline(73, 24, 73, 61, 15, 65, 15, 65);
@@ -564,25 +585,25 @@ function curves(p5, fn){
    *   point(73, 24);
    *   point(73, 61);
    *
-   *   // Draw the control points in red.
+   *   // Draw the points in red.
    *   stroke(255, 0, 0);
    *   point(x1, y1);
    *   point(15, 65);
    * }
    *
-   * // Start changing the first control point if the user clicks near it.
+   * // Start changing the first point if the user clicks near it.
    * function mousePressed() {
    *   if (dist(mouseX, mouseY, x1, y1) < 20) {
    *     isChanging = true;
    *   }
    * }
    *
-   * // Stop changing the first control point when the user releases the mouse.
+   * // Stop changing the first point when the user releases the mouse.
    * function mouseReleased() {
    *   isChanging = false;
    * }
    *
-   * // Update the first control point while the user drags the mouse.
+   * // Update the first point while the user drags the mouse.
    * function mouseDragged() {
    *   if (isChanging === true) {
    *     x1 = mouseX;
@@ -598,7 +619,10 @@ function curves(p5, fn){
    *   createCanvas(100, 100);
    *
    *   background('skyblue');
-   *
+   * 
+   *   // Exclude the ends—skip the outer spans (p0→p1 and p2→p3) so only the middle span (p1→p2) is drawn.
+   *   splineProperty('ends', EXCLUDE);
+   * 
    *   // Draw the red balloon.
    *   fill('red');
    *   spline(-150, 275, 50, 60, 50, 60, 250, 275);
@@ -621,7 +645,10 @@ function curves(p5, fn){
    *
    * function draw() {
    *   background('skyblue');
-   *
+   * 
+   *   // Exclude the ends—skip the outer spans (p0→p1 and p2→p3) so only the middle span (p1→p2) is drawn.
+   *   splineProperty('ends', EXCLUDE);
+   * 
    *   // Rotate around the y-axis.
    *   rotateY(frameCount * 0.01);
    *
@@ -640,16 +667,16 @@ function curves(p5, fn){
    * @method spline
    * @param  {Number} x1
    * @param  {Number} y1
-   * @param  {Number} z1 z-coordinate of the first control point.
+   * @param  {Number} z1 z-coordinate of point p0.
    * @param  {Number} x2
    * @param  {Number} y2
-   * @param  {Number} z2 z-coordinate of the first anchor point.
+   * @param  {Number} z2 z-coordinate of point p1.
    * @param  {Number} x3
    * @param  {Number} y3
-   * @param  {Number} z3 z-coordinate of the second anchor point.
+   * @param  {Number} z3 z-coordinate of point p2.
    * @param  {Number} x4
    * @param  {Number} y4
-   * @param  {Number} z4 z-coordinate of the second control point.
+   * @param  {Number} z4 z-coordinate of point p3.
    * @chainable
    */
   fn.spline = function(...args) {
@@ -664,30 +691,30 @@ function curves(p5, fn){
   /**
    * Calculates coordinates along a spline curve using interpolation.
    *
-   * `splinePoint()` calculates coordinates along a spline curve using the
-   * anchor and control points. It expects points in the same order as the
+   * `splinePoint()` calculates coordinates along a spline curve using four
+   * points p0, p1, p2, p3. It expects points in the same order as the
    * <a href="#/p5/spline">spline()</a> function. `splinePoint()` works one axis
-   * at a time. Passing the anchor and control points' x-coordinates will
-   * calculate the x-coordinate of a point on the curve. Passing the anchor and
-   * control points' y-coordinates will calculate the y-coordinate of a point on
+   * at a time. Passing the points' x-coordinates will
+   * calculate the x-coordinate of a point on the curve. Passing the
+   * points' y-coordinates will calculate the y-coordinate of a point on
    * the curve.
    *
-   * The first parameter, `a`, is the coordinate of the first control point.
+   * The first parameter, `a`, is the coordinate of point p0.
    *
-   * The second and third parameters, `b` and `c`, are the coordinates of the
-   * anchor points.
+   * The second and third parameters, `b` and `c`, are the coordinates of
+   * points p1 and p2.
    *
-   * The fourth parameter, `d`, is the coordinate of the last control point.
+   * The fourth parameter, `d`, is the coordinate of point p3.
    *
-   * The fifth parameter, `t`, is the amount to interpolate along the curve. 0
-   * is the first anchor point, 1 is the second anchor point, and 0.5 is halfway
+   * The fifth parameter, `t`, is the amount to interpolate along the span
+   * from p1 to p2. `t = 0` is p1, `t = 1` is p2, and `t = 0.5` is halfway
    * between them.
    *
    * @method splinePoint
-   * @param {Number} a coordinate of first control point.
-   * @param {Number} b coordinate of first anchor point.
-   * @param {Number} c coordinate of second anchor point.
-   * @param {Number} d coordinate of second control point.
+   * @param {Number} a coordinate of point p0.
+   * @param {Number} b coordinate of point p1.
+   * @param {Number} c coordinate of point p2.
+   * @param {Number} d coordinate of point p3.
    * @param {Number} t amount to interpolate between 0 and 1.
    * @return {Number} coordinate of a point on the curve.
    *
@@ -699,7 +726,8 @@ function curves(p5, fn){
    *
    *   background(200);
    *
-   *   // Set the coordinates for the curve's anchor and control points.
+   *
+   *   // Set the coordinates for the curve's four points (p0, p1, p2, p3).
    *   let x1 = 5;
    *   let y1 = 26;
    *   let x2 = 73;
@@ -747,7 +775,7 @@ function curves(p5, fn){
    * function draw() {
    *   background(200);
    *
-   *   // Set the coordinates for the curve's anchor and control points.
+   *   // Set the coordinates for the curve's four points (p0, p1, p2, p3).
    *   let x1 = 5;
    *   let y1 = 26;
    *   let x2 = 73;
@@ -773,6 +801,7 @@ function curves(p5, fn){
    * </code>
    * </div>
    */
+
   fn.splinePoint = function(a, b, c, d, t) {
     const s = this._renderer.states.splineProperties.tightness,
       t3 = t * t * t,
@@ -790,42 +819,82 @@ function curves(p5, fn){
    * Tangent lines skim the surface of a curve. A tangent line's slope equals
    * the curve's slope at the point where it intersects.
    *
-   * `splineTangent()` calculates coordinates along a tangent line using the
-   * spline curve's anchor and control points. It expects points in the same
-   * order as the <a href="#/p5/spline">spline()</a> function. `splineTangent()`
-   * works one axis at a time. Passing the anchor and control points'
-   * x-coordinates will calculate the x-coordinate of a point on the tangent
-   * line. Passing the anchor and control points' y-coordinates will calculate
-   * the y-coordinate of a point on the tangent line.
-   *
-   * The first parameter, `a`, is the coordinate of the first control point.
+   * `splineTangent()` calculates coordinates along a tangent line using four
+   * points p0, p1, p2, p3. It expects points in the same order as the
+   * <a href="#/p5/spline">spline()</a> function. `splineTangent()` works one
+   * axis at a time. Passing the points' x-coordinates returns the x-component of 
+   * the tangent vector; passing the points' y-coordinates returns the y-component.
+   * The first parameter, `a`, is the coordinate of point p0.
    *
-   * The second and third parameters, `b` and `c`, are the coordinates of the
-   * anchor points.
+   * The second and third parameters, `b` and `c`, are the coordinates of
+   * points p1 and p2.
    *
-   * The fourth parameter, `d`, is the coordinate of the last control point.
+   * The fourth parameter, `d`, is the coordinate of point p3.
    *
-   * The fifth parameter, `t`, is the amount to interpolate along the curve. 0
-   * is the first anchor point, 1 is the second anchor point, and 0.5 is halfway
+   * The fifth parameter, `t`, is the amount to interpolate along the span
+   * from p1 to p2. `t = 0` is p1, `t = 1` is p2, and `t = 0.5` is halfway
    * between them.
    *
    * @method splineTangent
-   * @param {Number} a coordinate of first control point.
-   * @param {Number} b coordinate of first anchor point.
-   * @param {Number} c coordinate of second anchor point.
-   * @param {Number} d coordinate of second control point.
+   * @param {Number} a coordinate of point p0.
+   * @param {Number} b coordinate of point p1.
+   * @param {Number} c coordinate of point p2.
+   * @param {Number} d coordinate of point p3.
    * @param {Number} t amount to interpolate between 0 and 1.
    * @return {Number} coordinate of a point on the tangent line.
    *
    * @example
    * <div>
    * <code>
    * function setup() {
+   *   createCanvas(120, 120);
+   *   describe('A black spline on a gray canvas. A red dot moves along the curve on its own. A short line shows the tangent direction at the dot.');
+   * }
+   *
+   * function draw() {
+   *   background(240);
+   *
+   *   const x1 = 15, y1 = 40;
+   *   const x2 = 90, y2 = 25;
+   *   const x3 = 95, y3 = 95;
+   *   const x4 = 30, y4 = 110;
+   *
+   *   noFill();
+   *   stroke(0);
+   *   strokeWeight(2);
+   *   spline(x1, y1, x2, y2, x3, y3, x4, y4);
+   *
+   *   const t = 0.5 + 0.5 * sin(frameCount * 0.03);
+   *
+   *   const px = splinePoint(x1, x2, x3, x4, t);
+   *   const py = splinePoint(y1, y2, y3, y4, t);
+   *
+   *   let tx = splineTangent(x1, x2, x3, x4, t);
+   *   let ty = splineTangent(y1, y2, y3, y4, t);
+   *
+   *   const m = Math.hypot(tx, ty) || 1;
+   *   tx = (tx / m) * 16;
+   *   ty = (ty / m) * 16;
+   *
+   *   stroke(0);
+   *   strokeWeight(2);
+   *   line(px, py, px + tx, py + ty);
+   *
+   *   noStroke();
+   *   fill('red');
+   *   circle(px, py, 7);
+   * }
+   * </code>
+   * </div>
+   * 
+   * <div>
+   * <code>
+   * function setup() {
    *   createCanvas(100, 100);
    *
    *   background(200);
    *
-   *   // Set the coordinates for the curve's anchor and control points.
+   *   // Set the coordinates for the curve's four points (p0, p1, p2, p3).
    *   let x1 = 5;
    *   let y1 = 26;
    *   let x2 = 73;