diff --git a/src/core/constants.js b/src/core/constants.js
index 8900741a4d..241e67066a 100644
--- a/src/core/constants.js
+++ b/src/core/constants.js
@@ -86,121 +86,546 @@ export const WAIT = 'wait';
// TRIGONOMETRY
/**
- * HALF_PI is a mathematical constant with the value
- * 1.57079632679489661923. It is half the ratio of the
- * circumference of a circle to its diameter. It is useful in
- * combination with the trigonometric functions sin() and cos().
+ * A `Number` constant that's approximately 1.5708.
+ *
+ * `HALF_PI` is half the value of the mathematical constant π. It's useful for
+ * many tasks that involve rotation and oscillation. For example, calling
+ * `rotate(HALF_PI)` rotates the coordinate system `HALF_PI` radians, which is
+ * a quarter turn (90˚).
+ *
+ * Note: `TWO_PI` radians equals 360˚, `PI` radians equals 180˚, `HALF_PI`
+ * radians equals 90˚, and `QUARTER_PI` radians equals 45˚.
*
* @property {Number} HALF_PI
* @final
*
* @example
- *
- * arc(50, 50, 80, 80, 0, HALF_PI);
- *
+ *
+ *
+ * function setup() {
+ * createCanvas(100, 100);
+ *
+ * background(200);
+ *
+ * // Draw an arc from 0 to HALF_PI.
+ * arc(50, 50, 80, 80, 0, HALF_PI);
+ *
+ * describe('The bottom-right quarter of a circle drawn in white on a gray background.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * function setup() {
+ * createCanvas(100, 100);
+ *
+ * background(200);
+ *
+ * // Translate the origin to the center.
+ * translate(50, 50);
+ *
+ * // Draw a line.
+ * line(0, 0, 40, 0);
+ *
+ * // Rotate a quarter turn.
+ * rotate(HALF_PI);
+ *
+ * // Draw the same line, rotated.
+ * line(0, 0, 40, 0);
+ *
+ * describe('Two black lines on a gray background. One line extends from the center to the right. The other line extends from the center to the bottom.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * function setup() {
+ * createCanvas(100, 100);
+ *
+ * describe(
+ * 'A red circle and a blue circle oscillate from left to right on a gray background. The red circle appears to chase the blue circle.'
+ * );
+ * }
*
- * @alt
- * 80×80 white quarter-circle with curve toward bottom right of canvas.
+ * function draw() {
+ * background(200);
+ *
+ * // Translate the origin to the center.
+ * translate(50, 50);
+ *
+ * // Calculate the x-coordinates.
+ * let x1 = 40 * sin(frameCount * 0.05);
+ * let x2 = 40 * sin(frameCount * 0.05 + HALF_PI);
+ *
+ * // Style the oscillators.
+ * noStroke();
+ *
+ * // Draw the red oscillator.
+ * fill(255, 0, 0);
+ * circle(x1, 0, 20);
+ *
+ * // Draw the blue oscillator.
+ * fill(0, 0, 255);
+ * circle(x2, 0, 20);
+ * }
+ *
+ *
*/
export const HALF_PI = _PI / 2;
+
/**
- * PI is a mathematical constant with the value
- * 3.14159265358979323846. It is the ratio of the circumference
- * of a circle to its diameter. It is useful in combination with
- * the trigonometric functions sin() and cos().
+ * A `Number` constant that's approximately 3.1416.
+ *
+ * `PI` is the mathematical constant π. It's useful for many tasks that
+ * involve rotation and oscillation. For example, calling `rotate(PI)` rotates
+ * the coordinate system `PI` radians, which is a half turn (180˚).
+ *
+ * Note: `TWO_PI` radians equals 360˚, `PI` radians equals 180˚, `HALF_PI`
+ * radians equals 90˚, and `QUARTER_PI` radians equals 45˚.
*
* @property {Number} PI
* @final
*
* @example
- *
- * arc(50, 50, 80, 80, 0, PI);
- *
+ *
+ *
+ * function setup() {
+ * createCanvas(100, 100);
+ *
+ * background(200);
+ *
+ * // Draw an arc from 0 to PI.
+ * arc(50, 50, 80, 80, 0, PI);
+ *
+ * describe('The bottom half of a circle drawn in white on a gray background.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * function setup() {
+ * createCanvas(100, 100);
+ *
+ * background(200);
+ *
+ * // Translate the origin to the center.
+ * translate(50, 50);
+ *
+ * // Draw a line.
+ * line(0, 0, 40, 0);
*
- * @alt
- * white half-circle with curve toward bottom of canvas.
+ * // Rotate a half turn.
+ * rotate(PI);
+ *
+ * // Draw the same line, rotated.
+ * line(0, 0, 40, 0);
+ *
+ * describe('A horizontal black line on a gray background.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * function setup() {
+ * createCanvas(100, 100);
+ *
+ * describe(
+ * 'A red circle and a blue circle oscillate from left to right on a gray background. The circles drift apart, then meet in the middle, over and over again.'
+ * );
+ * }
+ *
+ * function draw() {
+ * background(200);
+ *
+ * // Translate the origin to the center.
+ * translate(50, 50);
+ *
+ * // Calculate the x-coordinates.
+ * let x1 = 40 * sin(frameCount * 0.05);
+ * let x2 = 40 * sin(frameCount * 0.05 + PI);
+ *
+ * // Style the oscillators.
+ * noStroke();
+ *
+ * // Draw the red oscillator.
+ * fill(255, 0, 0);
+ * circle(x1, 0, 20);
+ *
+ * // Draw the blue oscillator.
+ * fill(0, 0, 255);
+ * circle(x2, 0, 20);
+ * }
+ *
+ *
*/
export const PI = _PI;
+
/**
- * QUARTER_PI is a mathematical constant with the value 0.7853982.
- * It is one quarter the ratio of the circumference of a circle to
- * its diameter. It is useful in combination with the trigonometric
- * functions sin() and cos().
+ * A `Number` constant that's approximately 0.7854.
+ *
+ * `QUARTER_PI` is one-fourth the value of the mathematical constant π. It's
+ * useful for many tasks that involve rotation and oscillation. For example,
+ * calling `rotate(QUARTER_PI)` rotates the coordinate system `QUARTER_PI`
+ * radians, which is an eighth of a turn (45˚).
+ *
+ * Note: `TWO_PI` radians equals 360˚, `PI` radians equals 180˚, `HALF_PI`
+ * radians equals 90˚, and `QUARTER_PI` radians equals 45˚.
*
* @property {Number} QUARTER_PI
* @final
*
* @example
- *
- * arc(50, 50, 80, 80, 0, QUARTER_PI);
- *
+ *
+ *
+ * function setup() {
+ * createCanvas(100, 100);
+ *
+ * background(200);
+ *
+ * // Draw an arc from 0 to QUARTER_PI.
+ * arc(50, 50, 80, 80, 0, QUARTER_PI);
+ *
+ * describe('A one-eighth slice of a circle drawn in white on a gray background.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * function setup() {
+ * createCanvas(100, 100);
+ *
+ * background(200);
+ *
+ * // Translate the origin to the center.
+ * translate(50, 50);
+ *
+ * // Draw a line.
+ * line(0, 0, 40, 0);
+ *
+ * // Rotate an eighth turn.
+ * rotate(QUARTER_PI);
+ *
+ * // Draw the same line, rotated.
+ * line(0, 0, 40, 0);
+ *
+ * describe('Two black lines that form a "V" opening towards the bottom-right corner of a gray square.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * function setup() {
+ * createCanvas(100, 100);
+ *
+ * describe(
+ * 'A red circle and a blue circle oscillate from left to right on a gray background. The red circle appears to chase the blue circle.'
+ * );
+ * }
+ *
+ * function draw() {
+ * background(200);
+ *
+ * // Translate the origin to the center.
+ * translate(50, 50);
+ *
+ * // Calculate the x-coordinates.
+ * let x1 = 40 * sin(frameCount * 0.05);
+ * let x2 = 40 * sin(frameCount * 0.05 + QUARTER_PI);
+ *
+ * // Style the oscillators.
+ * noStroke();
*
- * @alt
- * white eighth-circle rotated about 40 degrees with curve bottom right canvas.
+ * // Draw the red oscillator.
+ * fill(255, 0, 0);
+ * circle(x1, 0, 20);
+ *
+ * // Draw the blue oscillator.
+ * fill(0, 0, 255);
+ * circle(x2, 0, 20);
+ * }
+ *
+ *
*/
export const QUARTER_PI = _PI / 4;
+
/**
- * TAU is an alias for TWO_PI, a mathematical constant with the
- * value 6.28318530717958647693. It is twice the ratio of the
- * circumference of a circle to its diameter. It is useful in
- * combination with the trigonometric functions sin() and cos().
+ * A `Number` constant that's approximately 6.2382.
+ *
+ * `TAU` is twice the value of the mathematical constant π. It's useful for
+ * many tasks that involve rotation and oscillation. For example, calling
+ * `rotate(TAU)` rotates the coordinate system `TAU` radians, which is one
+ * full turn (360˚). `TAU` and `TWO_PI` are equal.
+ *
+ * Note: `TAU` radians equals 360˚, `PI` radians equals 180˚, `HALF_PI`
+ * radians equals 90˚, and `QUARTER_PI` radians equals 45˚.
*
* @property {Number} TAU
* @final
*
* @example
- *
- * arc(50, 50, 80, 80, 0, TAU);
- *
+ *
+ *
+ * function setup() {
+ * createCanvas(100, 100);
+ *
+ * background(200);
+ *
+ * // Draw an arc from 0 to TAU.
+ * arc(50, 50, 80, 80, 0, TAU);
+ *
+ * describe('A white circle drawn on a gray background.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * function setup() {
+ * createCanvas(100, 100);
+ *
+ * background(200);
+ *
+ * // Translate the origin to the center.
+ * translate(50, 50);
+ *
+ * // Draw a line.
+ * line(0, 0, 40, 0);
+ *
+ * // Rotate a full turn.
+ * rotate(TAU);
+ *
+ * // Style the second line.
+ * strokeWeight(5);
+ *
+ * // Draw the same line, shorter and rotated.
+ * line(0, 0, 20, 0);
+ *
+ * describe(
+ * 'Two horizontal black lines on a gray background. A thick line extends from the center toward the right. A thin line extends from the end of the thick line.'
+ * );
+ * }
+ *
+ *
*
- * @alt
- * 80×80 white ellipse shape in center of canvas.
+ *
+ *
+ * function setup() {
+ * createCanvas(100, 100);
+ *
+ * describe(
+ * 'A red circle with a blue center oscillates from left to right on a gray background.'
+ * );
+ * }
+ *
+ * function draw() {
+ * background(200);
+ *
+ * // Translate the origin to the center.
+ * translate(50, 50);
+ *
+ * // Calculate the x-coordinates.
+ * let x1 = 40 * sin(frameCount * 0.05);
+ * let x2 = 40 * sin(frameCount * 0.05 + TAU);
+ *
+ * // Style the oscillators.
+ * noStroke();
+ *
+ * // Draw the red oscillator.
+ * fill(255, 0, 0);
+ * circle(x1, 0, 20);
+ *
+ * // Draw the blue oscillator, smaller.
+ * fill(0, 0, 255);
+ * circle(x2, 0, 10);
+ * }
+ *
+ *
*/
export const TAU = _PI * 2;
+
/**
- * TWO_PI is a mathematical constant with the value
- * 6.28318530717958647693. It is twice the ratio of the
- * circumference of a circle to its diameter. It is useful in
- * combination with the trigonometric functions sin() and cos().
+ * A `Number` constant that's approximately 6.2382.
+ *
+ * `TWO_PI` is twice the value of the mathematical constant π. It's useful for
+ * many tasks that involve rotation and oscillation. For example, calling
+ * `rotate(TWO_PI)` rotates the coordinate system `TWO_PI` radians, which is
+ * one full turn (360˚). `TWO_PI` and `TAU` are equal.
+ *
+ * Note: `TWO_PI` radians equals 360˚, `PI` radians equals 180˚, `HALF_PI`
+ * radians equals 90˚, and `QUARTER_PI` radians equals 45˚.
*
* @property {Number} TWO_PI
* @final
*
* @example
- *
- * arc(50, 50, 80, 80, 0, TWO_PI);
- *
+ *
+ *
+ * function setup() {
+ * createCanvas(100, 100);
+ *
+ * background(200);
+ *
+ * // Draw an arc from 0 to TWO_PI.
+ * arc(50, 50, 80, 80, 0, TWO_PI);
+ *
+ * describe('A white circle drawn on a gray background.');
+ * }
+ *
+ *
+ *
+ *
+ *
+ * function setup() {
+ * createCanvas(100, 100);
+ *
+ * background(200);
+ *
+ * // Translate the origin to the center.
+ * translate(50, 50);
+ *
+ * // Draw a line.
+ * line(0, 0, 40, 0);
+ *
+ * // Rotate a full turn.
+ * rotate(TWO_PI);
+ *
+ * // Style the second line.
+ * strokeWeight(5);
+ *
+ * // Draw the same line, shorter and rotated.
+ * line(0, 0, 20, 0);
+ *
+ * describe(
+ * 'Two horizontal black lines on a gray background. A thick line extends from the center toward the right. A thin line extends from the end of the thick line.'
+ * );
+ * }
+ *
+ *
+ *
+ *
+ *
+ * function setup() {
+ * createCanvas(100, 100);
+ *
+ * describe(
+ * 'A red circle with a blue center oscillates from left to right on a gray background.'
+ * );
+ * }
+ *
+ * function draw() {
+ * background(200);
+ *
+ * // Translate the origin to the center.
+ * translate(50, 50);
*
- * @alt
- * 80×80 white ellipse shape in center of canvas.
+ * // Calculate the x-coordinates.
+ * let x1 = 40 * sin(frameCount * 0.05);
+ * let x2 = 40 * sin(frameCount * 0.05 + TWO_PI);
+ *
+ * // Style the oscillators.
+ * noStroke();
+ *
+ * // Draw the red oscillator.
+ * fill(255, 0, 0);
+ * circle(x1, 0, 20);
+ *
+ * // Draw the blue oscillator, smaller.
+ * fill(0, 0, 255);
+ * circle(x2, 0, 10);
+ * }
+ *
+ *
*/
export const TWO_PI = _PI * 2;
+
/**
- * Constant to be used with the angleMode() function, to set the mode in
- * which p5.js interprets and calculates angles (either DEGREES or RADIANS).
+ * A `String` constant that's used to set the
+ * angleMode().
+ *
+ * By default, functions such as rotate() and
+ * sin() expect angles measured in units of radians.
+ * Calling `angleMode(DEGREES)` ensures that angles are measured in units of
+ * degrees.
+ *
+ * Note: `TWO_PI` radians equals 360˚.
+ *
* @property {String} DEGREES
* @final
*
* @example
- *
+ *
+ *
* function setup() {
+ * createCanvas(100, 100);
+ *
+ * background(200);
+ *
+ * // Draw a red arc from 0 to HALF_PI radians.
+ * fill(255, 0, 0);
+ * arc(50, 50, 80, 80, 0, HALF_PI);
+ *
+ * // Use degrees.
* angleMode(DEGREES);
+ *
+ * // Draw a blue arc from 90˚ to 180˚.
+ * fill(0, 0, 255);
+ * arc(50, 50, 80, 80, 90, 180);
+ *
+ * describe('The bottom half of a circle drawn on a gray background. The bottom-right quarter is red. The bottom-left quarter is blue.');
* }
- *
+ *
+ *
+ *
+ *
* function setup() {
+ * createCanvas(100, 100);
+ *
+ * background(200);
+ *
+ * // Use degrees.
+ * angleMode(DEGREES);
+ *
+ * // Draw a red arc from 0˚ to 90˚.
+ * fill(255, 0, 0);
+ * arc(50, 50, 80, 80, 0, 90);
+ *
+ * // Use radians.
* angleMode(RADIANS);
+ *
+ * // Draw a blue arc from HALF_PI to PI.
+ * fill(0, 0, 255);
+ * arc(50, 50, 80, 80, HALF_PI, PI);
+ *
+ * describe('The bottom half of a circle drawn on a gray background. The bottom-right quarter is red. The bottom-left quarter is blue.');
* }
- *
+ *
+ *