@js-draw/math 1.22.0 → 1.23.1

package/dist/cjs/Color4.d.ts

@@ -28,9 +28,32 @@ export declare class Color4 {
      * Each component should be in the range [0, 1].
      */
     static ofRGB(red: number, green: number, blue: number): Color4;
+    /**
+     * Creates a color from red, green, blue, and transparency components. Each component should
+     * be in the range $[0, 1]$.
+     */
     static ofRGBA(red: number, green: number, blue: number, alpha: number): Color4;
+    /**
+     * Creates a color from an RGB (or RGBA) array.
+     *
+     * This is similar to {@link ofRGB} and {@link ofRGBA}, but, by default, takes values
+     * that range from 0 to 255.
+     *
+     * If the array values instead range from 0-1, pass `maxValue` as `1`.
+     */
+    static fromRGBArray(array: Uint8Array | Uint8ClampedArray | number[], maxValue?: number): Color4;
+    /**
+     * Creates a `Color4` from a three or four-component hexadecimal
+     * [color string](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet).
+     *
+     * Example:
+     * ```ts,runnable,console
+     * import { Color4 } from '@js-draw/math';
+     * console.log(Color4.fromHex('#ff0'));
+     * ```
+     */
     static fromHex(hexString: string): Color4;
-    /** Like fromHex, but can handle additional colors if an `HTMLCanvasElement` is available. */
+    /** Like {@link fromHex}, but can handle additional colors if an `HTMLCanvasElement` is available. */
     static fromString(text: string): Color4;
     /** @returns true if `this` and `other` are approximately equal. */
     eq(other: Color4 | null | undefined): boolean;

package/dist/cjs/Color4.js

@@ -42,6 +42,10 @@ class Color4 {
     static ofRGB(red, green, blue) {
         return Color4.ofRGBA(red, green, blue, 1.0);
     }
+    /**
+     * Creates a color from red, green, blue, and transparency components. Each component should
+     * be in the range $[0, 1]$.
+     */
     static ofRGBA(red, green, blue, alpha) {
         red = Math.max(0, Math.min(red, 1));
         green = Math.max(0, Math.min(green, 1));
@@ -49,6 +53,34 @@ class Color4 {
         alpha = Math.max(0, Math.min(alpha, 1));
         return new Color4(red, green, blue, alpha);
     }
+    /**
+     * Creates a color from an RGB (or RGBA) array.
+     *
+     * This is similar to {@link ofRGB} and {@link ofRGBA}, but, by default, takes values
+     * that range from 0 to 255.
+     *
+     * If the array values instead range from 0-1, pass `maxValue` as `1`.
+     */
+    static fromRGBArray(array, maxValue = 255) {
+        const red = array[0];
+        const green = array[1] ?? red;
+        const blue = array[2] ?? red;
+        let alpha = 255;
+        if (3 < array.length) {
+            alpha = array[3];
+        }
+        return Color4.ofRGBA(red / maxValue, green / maxValue, blue / maxValue, alpha / maxValue);
+    }
+    /**
+     * Creates a `Color4` from a three or four-component hexadecimal
+     * [color string](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet).
+     *
+     * Example:
+     * ```ts,runnable,console
+     * import { Color4 } from '@js-draw/math';
+     * console.log(Color4.fromHex('#ff0'));
+     * ```
+     */
     static fromHex(hexString) {
         // Remove starting '#' (if present)
         hexString = (hexString.match(/^[#]?(.*)$/) ?? [])[1];
@@ -77,7 +109,7 @@ class Color4 {
         }
         return Color4.ofRGBA(components[0], components[1], components[2], components[3]);
     }
-    /** Like fromHex, but can handle additional colors if an `HTMLCanvasElement` is available. */
+    /** Like {@link fromHex}, but can handle additional colors if an `HTMLCanvasElement` is available. */
     static fromString(text) {
         if (text.startsWith('#')) {
             return Color4.fromHex(text);

package/dist/cjs/Mat33.d.ts

@@ -206,6 +206,26 @@ export declare class Mat33 {
      * $$
      */
     static translation(amount: Vec2): Mat33;
+    /**
+     * Creates a matrix for rotating `Vec2`s about `center` by some number of `radians`.
+     *
+     * For this function, {@link Vec2}s are considered to be points in 2D space.
+     *
+     * For example,
+     * ```ts,runnable,console
+     * import { Mat33, Vec2 } from '@js-draw/math';
+     *
+     * const halfCircle = Math.PI; // PI radians = 180 degrees = 1/2 circle
+     * const center = Vec2.of(1, 1); // The point (1,1)
+     * const rotationMatrix = Mat33.zRotation(halfCircle, center);
+     *
+     * console.log(
+     *   'Rotating (0,0) 180deg about', center, 'results in',
+     *   // Rotates (0,0)
+     *   rotationMatrix.transformVec2(Vec2.zero),
+     * );
+     * ```
+     */
     static zRotation(radians: number, center?: Point2): Mat33;
     static scaling2D(amount: number | Vec2, center?: Point2): Mat33;
     /**

package/dist/cjs/Mat33.js

@@ -362,6 +362,26 @@ class Mat33 {
         //   ...
         return new Mat33(1, 0, amount.x, 0, 1, amount.y, 0, 0, 1);
     }
+    /**
+     * Creates a matrix for rotating `Vec2`s about `center` by some number of `radians`.
+     *
+     * For this function, {@link Vec2}s are considered to be points in 2D space.
+     *
+     * For example,
+     * ```ts,runnable,console
+     * import { Mat33, Vec2 } from '@js-draw/math';
+     *
+     * const halfCircle = Math.PI; // PI radians = 180 degrees = 1/2 circle
+     * const center = Vec2.of(1, 1); // The point (1,1)
+     * const rotationMatrix = Mat33.zRotation(halfCircle, center);
+     *
+     * console.log(
+     *   'Rotating (0,0) 180deg about', center, 'results in',
+     *   // Rotates (0,0)
+     *   rotationMatrix.transformVec2(Vec2.zero),
+     * );
+     * ```
+     */
     static zRotation(radians, center = Vec2_1.Vec2.zero) {
         if (radians === 0) {
             return Mat33.identity;

package/dist/cjs/Vec3.d.ts

@@ -150,7 +150,7 @@ export interface Vec3 {
     map(fn: (component: number, index: number) => number): Vec3;
     asArray(): [number, number, number];
     /**
-     * [fuzz] The maximum difference between two components for this and [other]
+     * @param tolerance The maximum difference between two components for this and [other]
      * to be considered equal.
      *
      * @example
@@ -200,12 +200,16 @@ declare class Vec2Impl implements Vec3 {
     toString(): string;
 }
 /**
- * A `Vec2` is a `Vec3` optimized for working in a plane. As such, they have an
+ * A `Vec2` is a {@link Vec3} optimized for working in a plane. `Vec2`s have an
  * always-zero `z` component.
  *
  * ```ts,runnable,console
  * import { Vec2 } from '@js-draw/math';
- * console.log(Vec2.of(1, 2));
+ *
+ * const v = Vec2.of(1, 2);
+ * console.log('a Vec2:', v);
+ * console.log('x component:', v.x);
+ * console.log('z component:', v.z);
  * ```
  */
 export declare namespace Vec2 {
@@ -240,6 +244,7 @@ export declare namespace Vec2 {
     /** The zero vector: A vector with x=0, y=0. */
     const zero: Vec2Impl;
 }
+/** Contains static methods for constructing a {@link Vec3}. */
 export declare namespace Vec3 {
     /**
      * Construct a vector from three components.
@@ -248,11 +253,15 @@ export declare namespace Vec3 {
      * ```ts,runnable,console
      * import { Vec3 } from '@js-draw/math';
      * const v1 = Vec3.of(1, 2, 3);
+     * console.log(v1.plus(Vec3.of(0, 100, 0)));
      * ```
      */
     const of: (x: number, y: number, z: number) => Vec3;
+    /** A unit vector in the x direction (`[1, 0, 0]`). */
     const unitX: Vec2Impl;
+    /** A unit vector in the y direction (`[0, 1, 0]`). */
     const unitY: Vec2Impl;
+    /** The zero vector (`[0, 0, 0]`). */
     const zero: Vec2Impl;
     /** A vector of length 1 in the z direction. */
     const unitZ: Vec3;

package/dist/cjs/Vec3.js

@@ -227,12 +227,16 @@ class Vec2Impl {
     }
 }
 /**
- * A `Vec2` is a `Vec3` optimized for working in a plane. As such, they have an
+ * A `Vec2` is a {@link Vec3} optimized for working in a plane. `Vec2`s have an
  * always-zero `z` component.
  *
  * ```ts,runnable,console
  * import { Vec2 } from '@js-draw/math';
- * console.log(Vec2.of(1, 2));
+ *
+ * const v = Vec2.of(1, 2);
+ * console.log('a Vec2:', v);
+ * console.log('x component:', v.x);
+ * console.log('z component:', v.z);
  * ```
  */
 var Vec2;
@@ -269,6 +273,7 @@ var Vec2;
     /** The zero vector: A vector with x=0, y=0. */
     Vec2.zero = Vec2.of(0, 0);
 })(Vec2 || (exports.Vec2 = Vec2 = {}));
+/** Contains static methods for constructing a {@link Vec3}. */
 var Vec3;
 (function (Vec3) {
     /**
@@ -278,6 +283,7 @@ var Vec3;
      * ```ts,runnable,console
      * import { Vec3 } from '@js-draw/math';
      * const v1 = Vec3.of(1, 2, 3);
+     * console.log(v1.plus(Vec3.of(0, 100, 0)));
      * ```
      */
     Vec3.of = (x, y, z) => {
@@ -288,8 +294,11 @@ var Vec3;
             return new Vec3Impl(x, y, z);
         }
     };
+    /** A unit vector in the x direction (`[1, 0, 0]`). */
     Vec3.unitX = Vec2.unitX;
+    /** A unit vector in the y direction (`[0, 1, 0]`). */
     Vec3.unitY = Vec2.unitY;
+    /** The zero vector (`[0, 0, 0]`). */
     Vec3.zero = Vec2.zero;
     /** A vector of length 1 in the z direction. */
     Vec3.unitZ = Vec3.of(0, 0, 1);

package/dist/cjs/lib.d.ts

@@ -1,4 +1,7 @@
 /**
+ * This package contains general math utilities used by `js-draw`.
+ * These include 2D and 3D vectors, 2D paths, and 3x3 matrices.
+ *
  * ```ts,runnable,console
  * import { Vec2, Mat33, Rect2 } from '@js-draw/math';
  *

package/dist/cjs/lib.js

@@ -1,5 +1,8 @@
 "use strict";
 /**
+ * This package contains general math utilities used by `js-draw`.
+ * These include 2D and 3D vectors, 2D paths, and 3x3 matrices.
+ *
  * ```ts,runnable,console
  * import { Vec2, Mat33, Rect2 } from '@js-draw/math';
  *

package/dist/cjs/shapes/BezierJSWrapper.d.ts

@@ -29,8 +29,10 @@ export declare abstract class BezierJSWrapper extends Parameterized2DShape {
      * @returns the curve evaluated at `t`.
      */
     at(t: number): Point2;
+    /** @returns the curve's directional derivative at `t`. */
     derivativeAt(t: number): Point2;
     secondDerivativeAt(t: number): Point2;
+    /** @returns the [normal vector](https://en.wikipedia.org/wiki/Normal_(geometry)) to this curve at `t`. */
     normal(t: number): Vec2;
     normalAt(t: number): Vec2;
     tangentAt(t: number): Vec2;

package/dist/cjs/shapes/BezierJSWrapper.js

@@ -63,12 +63,14 @@ class BezierJSWrapper extends Parameterized2DShape_1.default {
     at(t) {
         return Vec2_1.Vec2.ofXY(this.getBezier().get(t));
     }
+    /** @returns the curve's directional derivative at `t`. */
     derivativeAt(t) {
         return Vec2_1.Vec2.ofXY(this.getBezier().derivative(t));
     }
     secondDerivativeAt(t) {
         return Vec2_1.Vec2.ofXY(this.getBezier().dderivative(t));
     }
+    /** @returns the [normal vector](https://en.wikipedia.org/wiki/Normal_(geometry)) to this curve at `t`. */
     normal(t) {
         return Vec2_1.Vec2.ofXY(this.getBezier().normal(t));
     }

package/dist/cjs/shapes/Path.d.ts

@@ -3,6 +3,7 @@ import Mat33 from '../Mat33';
 import Rect2 from './Rect2';
 import { Point2 } from '../Vec2';
 import Parameterized2DShape from './Parameterized2DShape';
+/** Identifiers for different path commands. These commands can make up a {@link Path}. */
 export declare enum PathCommandType {
     LineTo = 0,
     MoveTo = 1,

package/dist/cjs/shapes/Path.js

@@ -13,6 +13,7 @@ const PointShape2D_1 = __importDefault(require("./PointShape2D"));
 const toRoundedString_1 = __importDefault(require("../rounding/toRoundedString"));
 const toStringOfSamePrecision_1 = __importDefault(require("../rounding/toStringOfSamePrecision"));
 const convexHull2Of_1 = __importDefault(require("../utils/convexHull2Of"));
+/** Identifiers for different path commands. These commands can make up a {@link Path}. */
 var PathCommandType;
 (function (PathCommandType) {
     PathCommandType[PathCommandType["LineTo"] = 0] = "LineTo";

package/dist/cjs/shapes/QuadraticBezier.d.ts

@@ -2,9 +2,26 @@ import { Point2, Vec2 } from '../Vec2';
 import BezierJSWrapper from './BezierJSWrapper';
 import Rect2 from './Rect2';
 /**
- * Represents a 2D Bézier curve.
+ * Represents a 2D [Bézier curve](https://en.wikipedia.org/wiki/B%C3%A9zier_curve).
  *
- * **Note**: Many Bézier operations use `bezier-js`'s.
+ * Example:
+ * ```ts,runnable,console
+ * import { QuadraticBezier, Vec2 } from '@js-draw/math';
+ *
+ * const startPoint = Vec2.of(4, 3);
+ * const controlPoint = Vec2.of(1, 1);
+ * const endPoint = Vec2.of(1, 3);
+ *
+ * const curve = new QuadraticBezier(
+ *   startPoint,
+ *   controlPoint,
+ *   endPoint,
+ * );
+ *
+ * console.log('Curve:', curve);
+ * ```
+ *
+ * **Note**: Some Bézier operations internally use the `bezier-js` library.
  */
 export declare class QuadraticBezier extends BezierJSWrapper {
     readonly p0: Point2;

package/dist/cjs/shapes/QuadraticBezier.js

@@ -9,12 +9,35 @@ const solveQuadratic_1 = __importDefault(require("../polynomial/solveQuadratic")
 const BezierJSWrapper_1 = __importDefault(require("./BezierJSWrapper"));
 const Rect2_1 = __importDefault(require("./Rect2"));
 /**
- * Represents a 2D Bézier curve.
+ * Represents a 2D [Bézier curve](https://en.wikipedia.org/wiki/B%C3%A9zier_curve).
  *
- * **Note**: Many Bézier operations use `bezier-js`'s.
+ * Example:
+ * ```ts,runnable,console
+ * import { QuadraticBezier, Vec2 } from '@js-draw/math';
+ *
+ * const startPoint = Vec2.of(4, 3);
+ * const controlPoint = Vec2.of(1, 1);
+ * const endPoint = Vec2.of(1, 3);
+ *
+ * const curve = new QuadraticBezier(
+ *   startPoint,
+ *   controlPoint,
+ *   endPoint,
+ * );
+ *
+ * console.log('Curve:', curve);
+ * ```
+ *
+ * **Note**: Some Bézier operations internally use the `bezier-js` library.
  */
 class QuadraticBezier extends BezierJSWrapper_1.default {
-    constructor(p0, p1, p2) {
+    constructor(
+    // Start point
+    p0, 
+    // Control point
+    p1, 
+    // End point
+    p2) {
         super();
         this.p0 = p0;
         this.p1 = p1;

package/dist/cjs/shapes/Rect2.d.ts

@@ -15,6 +15,18 @@ export interface RectTemplate {
 /**
  * Represents a rectangle in 2D space, parallel to the XY axes.
  *
+ * **Example**:
+ * ```ts,runnable,console
+ * import { Rect2, Vec2 } from '@js-draw/math';
+ *
+ * const rect = Rect2.fromCorners(
+ *   Vec2.of(0, 0),
+ *   Vec2.of(10, 10),
+ * );
+ * console.log('area', rect.area);
+ * console.log('topLeft', rect.topLeft);
+ * ```
+ *
  * `invariant: w ≥ 0, h ≥ 0, immutable`
  */
 export declare class Rect2 extends Abstract2DShape {
@@ -29,6 +41,7 @@ export declare class Rect2 extends Abstract2DShape {
     translatedBy(vec: Vec2): Rect2;
     resizedTo(size: Vec2): Rect2;
     containsPoint(other: Point2): boolean;
+    /** @returns true iff `other` is completely within this `Rect2`. */
     containsRect(other: Rect2): boolean;
     /**
      * @returns true iff this and `other` overlap

package/dist/cjs/shapes/Rect2.js

@@ -10,10 +10,30 @@ const Abstract2DShape_1 = __importDefault(require("./Abstract2DShape"));
 /**
  * Represents a rectangle in 2D space, parallel to the XY axes.
  *
+ * **Example**:
+ * ```ts,runnable,console
+ * import { Rect2, Vec2 } from '@js-draw/math';
+ *
+ * const rect = Rect2.fromCorners(
+ *   Vec2.of(0, 0),
+ *   Vec2.of(10, 10),
+ * );
+ * console.log('area', rect.area);
+ * console.log('topLeft', rect.topLeft);
+ * ```
+ *
  * `invariant: w ≥ 0, h ≥ 0, immutable`
  */
 class Rect2 extends Abstract2DShape_1.default {
-    constructor(x, y, w, h) {
+    constructor(
+    // Top left x coordinate
+    x, 
+    // Top left y coordinate
+    y, 
+    // Width
+    w, 
+    // Height
+    h) {
         super();
         this.x = x;
         this.y = y;
@@ -45,6 +65,7 @@ class Rect2 extends Abstract2DShape_1.default {
             this.x + this.w >= other.x &&
             this.y + this.h >= other.y);
     }
+    /** @returns true iff `other` is completely within this `Rect2`. */
     containsRect(other) {
         return (this.x <= other.x &&
             this.y <= other.y &&

package/dist/mjs/Color4.d.ts

@@ -28,9 +28,32 @@ export declare class Color4 {
      * Each component should be in the range [0, 1].
      */
     static ofRGB(red: number, green: number, blue: number): Color4;
+    /**
+     * Creates a color from red, green, blue, and transparency components. Each component should
+     * be in the range $[0, 1]$.
+     */
     static ofRGBA(red: number, green: number, blue: number, alpha: number): Color4;
+    /**
+     * Creates a color from an RGB (or RGBA) array.
+     *
+     * This is similar to {@link ofRGB} and {@link ofRGBA}, but, by default, takes values
+     * that range from 0 to 255.
+     *
+     * If the array values instead range from 0-1, pass `maxValue` as `1`.
+     */
+    static fromRGBArray(array: Uint8Array | Uint8ClampedArray | number[], maxValue?: number): Color4;
+    /**
+     * Creates a `Color4` from a three or four-component hexadecimal
+     * [color string](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet).
+     *
+     * Example:
+     * ```ts,runnable,console
+     * import { Color4 } from '@js-draw/math';
+     * console.log(Color4.fromHex('#ff0'));
+     * ```
+     */
     static fromHex(hexString: string): Color4;
-    /** Like fromHex, but can handle additional colors if an `HTMLCanvasElement` is available. */
+    /** Like {@link fromHex}, but can handle additional colors if an `HTMLCanvasElement` is available. */
     static fromString(text: string): Color4;
     /** @returns true if `this` and `other` are approximately equal. */
     eq(other: Color4 | null | undefined): boolean;

package/dist/mjs/Color4.mjs

@@ -36,6 +36,10 @@ export class Color4 {
     static ofRGB(red, green, blue) {
         return Color4.ofRGBA(red, green, blue, 1.0);
     }
+    /**
+     * Creates a color from red, green, blue, and transparency components. Each component should
+     * be in the range $[0, 1]$.
+     */
     static ofRGBA(red, green, blue, alpha) {
         red = Math.max(0, Math.min(red, 1));
         green = Math.max(0, Math.min(green, 1));
@@ -43,6 +47,34 @@ export class Color4 {
         alpha = Math.max(0, Math.min(alpha, 1));
         return new Color4(red, green, blue, alpha);
     }
+    /**
+     * Creates a color from an RGB (or RGBA) array.
+     *
+     * This is similar to {@link ofRGB} and {@link ofRGBA}, but, by default, takes values
+     * that range from 0 to 255.
+     *
+     * If the array values instead range from 0-1, pass `maxValue` as `1`.
+     */
+    static fromRGBArray(array, maxValue = 255) {
+        const red = array[0];
+        const green = array[1] ?? red;
+        const blue = array[2] ?? red;
+        let alpha = 255;
+        if (3 < array.length) {
+            alpha = array[3];
+        }
+        return Color4.ofRGBA(red / maxValue, green / maxValue, blue / maxValue, alpha / maxValue);
+    }
+    /**
+     * Creates a `Color4` from a three or four-component hexadecimal
+     * [color string](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet).
+     *
+     * Example:
+     * ```ts,runnable,console
+     * import { Color4 } from '@js-draw/math';
+     * console.log(Color4.fromHex('#ff0'));
+     * ```
+     */
     static fromHex(hexString) {
         // Remove starting '#' (if present)
         hexString = (hexString.match(/^[#]?(.*)$/) ?? [])[1];
@@ -71,7 +103,7 @@ export class Color4 {
         }
         return Color4.ofRGBA(components[0], components[1], components[2], components[3]);
     }
-    /** Like fromHex, but can handle additional colors if an `HTMLCanvasElement` is available. */
+    /** Like {@link fromHex}, but can handle additional colors if an `HTMLCanvasElement` is available. */
     static fromString(text) {
         if (text.startsWith('#')) {
             return Color4.fromHex(text);

package/dist/mjs/Mat33.d.ts

@@ -206,6 +206,26 @@ export declare class Mat33 {
      * $$
      */
     static translation(amount: Vec2): Mat33;
+    /**
+     * Creates a matrix for rotating `Vec2`s about `center` by some number of `radians`.
+     *
+     * For this function, {@link Vec2}s are considered to be points in 2D space.
+     *
+     * For example,
+     * ```ts,runnable,console
+     * import { Mat33, Vec2 } from '@js-draw/math';
+     *
+     * const halfCircle = Math.PI; // PI radians = 180 degrees = 1/2 circle
+     * const center = Vec2.of(1, 1); // The point (1,1)
+     * const rotationMatrix = Mat33.zRotation(halfCircle, center);
+     *
+     * console.log(
+     *   'Rotating (0,0) 180deg about', center, 'results in',
+     *   // Rotates (0,0)
+     *   rotationMatrix.transformVec2(Vec2.zero),
+     * );
+     * ```
+     */
     static zRotation(radians: number, center?: Point2): Mat33;
     static scaling2D(amount: number | Vec2, center?: Point2): Mat33;
     /**

package/dist/mjs/Mat33.mjs

@@ -356,6 +356,26 @@ export class Mat33 {
         //   ...
         return new Mat33(1, 0, amount.x, 0, 1, amount.y, 0, 0, 1);
     }
+    /**
+     * Creates a matrix for rotating `Vec2`s about `center` by some number of `radians`.
+     *
+     * For this function, {@link Vec2}s are considered to be points in 2D space.
+     *
+     * For example,
+     * ```ts,runnable,console
+     * import { Mat33, Vec2 } from '@js-draw/math';
+     *
+     * const halfCircle = Math.PI; // PI radians = 180 degrees = 1/2 circle
+     * const center = Vec2.of(1, 1); // The point (1,1)
+     * const rotationMatrix = Mat33.zRotation(halfCircle, center);
+     *
+     * console.log(
+     *   'Rotating (0,0) 180deg about', center, 'results in',
+     *   // Rotates (0,0)
+     *   rotationMatrix.transformVec2(Vec2.zero),
+     * );
+     * ```
+     */
     static zRotation(radians, center = Vec2.zero) {
         if (radians === 0) {
             return Mat33.identity;

package/dist/mjs/Vec3.d.ts

@@ -150,7 +150,7 @@ export interface Vec3 {
     map(fn: (component: number, index: number) => number): Vec3;
     asArray(): [number, number, number];
     /**
-     * [fuzz] The maximum difference between two components for this and [other]
+     * @param tolerance The maximum difference between two components for this and [other]
      * to be considered equal.
      *
      * @example
@@ -200,12 +200,16 @@ declare class Vec2Impl implements Vec3 {
     toString(): string;
 }
 /**
- * A `Vec2` is a `Vec3` optimized for working in a plane. As such, they have an
+ * A `Vec2` is a {@link Vec3} optimized for working in a plane. `Vec2`s have an
  * always-zero `z` component.
  *
  * ```ts,runnable,console
  * import { Vec2 } from '@js-draw/math';
- * console.log(Vec2.of(1, 2));
+ *
+ * const v = Vec2.of(1, 2);
+ * console.log('a Vec2:', v);
+ * console.log('x component:', v.x);
+ * console.log('z component:', v.z);
  * ```
  */
 export declare namespace Vec2 {
@@ -240,6 +244,7 @@ export declare namespace Vec2 {
     /** The zero vector: A vector with x=0, y=0. */
     const zero: Vec2Impl;
 }
+/** Contains static methods for constructing a {@link Vec3}. */
 export declare namespace Vec3 {
     /**
      * Construct a vector from three components.
@@ -248,11 +253,15 @@ export declare namespace Vec3 {
      * ```ts,runnable,console
      * import { Vec3 } from '@js-draw/math';
      * const v1 = Vec3.of(1, 2, 3);
+     * console.log(v1.plus(Vec3.of(0, 100, 0)));
      * ```
      */
     const of: (x: number, y: number, z: number) => Vec3;
+    /** A unit vector in the x direction (`[1, 0, 0]`). */
     const unitX: Vec2Impl;
+    /** A unit vector in the y direction (`[0, 1, 0]`). */
     const unitY: Vec2Impl;
+    /** The zero vector (`[0, 0, 0]`). */
     const zero: Vec2Impl;
     /** A vector of length 1 in the z direction. */
     const unitZ: Vec3;

package/dist/mjs/Vec3.mjs

@@ -224,12 +224,16 @@ class Vec2Impl {
     }
 }
 /**
- * A `Vec2` is a `Vec3` optimized for working in a plane. As such, they have an
+ * A `Vec2` is a {@link Vec3} optimized for working in a plane. `Vec2`s have an
  * always-zero `z` component.
  *
  * ```ts,runnable,console
  * import { Vec2 } from '@js-draw/math';
- * console.log(Vec2.of(1, 2));
+ *
+ * const v = Vec2.of(1, 2);
+ * console.log('a Vec2:', v);
+ * console.log('x component:', v.x);
+ * console.log('z component:', v.z);
  * ```
  */
 export var Vec2;
@@ -266,6 +270,7 @@ export var Vec2;
     /** The zero vector: A vector with x=0, y=0. */
     Vec2.zero = Vec2.of(0, 0);
 })(Vec2 || (Vec2 = {}));
+/** Contains static methods for constructing a {@link Vec3}. */
 export var Vec3;
 (function (Vec3) {
     /**
@@ -275,6 +280,7 @@ export var Vec3;
      * ```ts,runnable,console
      * import { Vec3 } from '@js-draw/math';
      * const v1 = Vec3.of(1, 2, 3);
+     * console.log(v1.plus(Vec3.of(0, 100, 0)));
      * ```
      */
     Vec3.of = (x, y, z) => {
@@ -285,8 +291,11 @@ export var Vec3;
             return new Vec3Impl(x, y, z);
         }
     };
+    /** A unit vector in the x direction (`[1, 0, 0]`). */
     Vec3.unitX = Vec2.unitX;
+    /** A unit vector in the y direction (`[0, 1, 0]`). */
     Vec3.unitY = Vec2.unitY;
+    /** The zero vector (`[0, 0, 0]`). */
     Vec3.zero = Vec2.zero;
     /** A vector of length 1 in the z direction. */
     Vec3.unitZ = Vec3.of(0, 0, 1);

package/dist/mjs/lib.d.ts

@@ -1,4 +1,7 @@
 /**
+ * This package contains general math utilities used by `js-draw`.
+ * These include 2D and 3D vectors, 2D paths, and 3x3 matrices.
+ *
  * ```ts,runnable,console
  * import { Vec2, Mat33, Rect2 } from '@js-draw/math';
  *

package/dist/mjs/lib.mjs

@@ -1,4 +1,7 @@
 /**
+ * This package contains general math utilities used by `js-draw`.
+ * These include 2D and 3D vectors, 2D paths, and 3x3 matrices.
+ *
  * ```ts,runnable,console
  * import { Vec2, Mat33, Rect2 } from '@js-draw/math';
  *

package/dist/mjs/shapes/BezierJSWrapper.d.ts

@@ -29,8 +29,10 @@ export declare abstract class BezierJSWrapper extends Parameterized2DShape {
      * @returns the curve evaluated at `t`.
      */
     at(t: number): Point2;
+    /** @returns the curve's directional derivative at `t`. */
     derivativeAt(t: number): Point2;
     secondDerivativeAt(t: number): Point2;
+    /** @returns the [normal vector](https://en.wikipedia.org/wiki/Normal_(geometry)) to this curve at `t`. */
     normal(t: number): Vec2;
     normalAt(t: number): Vec2;
     tangentAt(t: number): Vec2;

package/dist/mjs/shapes/BezierJSWrapper.mjs

@@ -57,12 +57,14 @@ export class BezierJSWrapper extends Parameterized2DShape {
     at(t) {
         return Vec2.ofXY(this.getBezier().get(t));
     }
+    /** @returns the curve's directional derivative at `t`. */
     derivativeAt(t) {
         return Vec2.ofXY(this.getBezier().derivative(t));
     }
     secondDerivativeAt(t) {
         return Vec2.ofXY(this.getBezier().dderivative(t));
     }
+    /** @returns the [normal vector](https://en.wikipedia.org/wiki/Normal_(geometry)) to this curve at `t`. */
     normal(t) {
         return Vec2.ofXY(this.getBezier().normal(t));
     }

package/dist/mjs/shapes/Path.d.ts

@@ -3,6 +3,7 @@ import Mat33 from '../Mat33';
 import Rect2 from './Rect2';
 import { Point2 } from '../Vec2';
 import Parameterized2DShape from './Parameterized2DShape';
+/** Identifiers for different path commands. These commands can make up a {@link Path}. */
 export declare enum PathCommandType {
     LineTo = 0,
     MoveTo = 1,

package/dist/mjs/shapes/Path.mjs

@@ -7,6 +7,7 @@ import  PointShape2D  from './PointShape2D.mjs';
 import  toRoundedString  from '../rounding/toRoundedString.mjs';
 import  toStringOfSamePrecision  from '../rounding/toStringOfSamePrecision.mjs';
 import  convexHull2Of  from '../utils/convexHull2Of.mjs';
+/** Identifiers for different path commands. These commands can make up a {@link Path}. */
 export var PathCommandType;
 (function (PathCommandType) {
     PathCommandType[PathCommandType["LineTo"] = 0] = "LineTo";

package/dist/mjs/shapes/QuadraticBezier.d.ts

@@ -2,9 +2,26 @@ import { Point2, Vec2 } from '../Vec2';
 import BezierJSWrapper from './BezierJSWrapper';
 import Rect2 from './Rect2';
 /**
- * Represents a 2D Bézier curve.
+ * Represents a 2D [Bézier curve](https://en.wikipedia.org/wiki/B%C3%A9zier_curve).
  *
- * **Note**: Many Bézier operations use `bezier-js`'s.
+ * Example:
+ * ```ts,runnable,console
+ * import { QuadraticBezier, Vec2 } from '@js-draw/math';
+ *
+ * const startPoint = Vec2.of(4, 3);
+ * const controlPoint = Vec2.of(1, 1);
+ * const endPoint = Vec2.of(1, 3);
+ *
+ * const curve = new QuadraticBezier(
+ *   startPoint,
+ *   controlPoint,
+ *   endPoint,
+ * );
+ *
+ * console.log('Curve:', curve);
+ * ```
+ *
+ * **Note**: Some Bézier operations internally use the `bezier-js` library.
  */
 export declare class QuadraticBezier extends BezierJSWrapper {
     readonly p0: Point2;

package/dist/mjs/shapes/QuadraticBezier.mjs

@@ -3,12 +3,35 @@ import  solveQuadratic  from '../polynomial/solveQuadratic.mjs';
 import  BezierJSWrapper  from './BezierJSWrapper.mjs';
 import  Rect2  from './Rect2.mjs';
 /**
- * Represents a 2D Bézier curve.
+ * Represents a 2D [Bézier curve](https://en.wikipedia.org/wiki/B%C3%A9zier_curve).
  *
- * **Note**: Many Bézier operations use `bezier-js`'s.
+ * Example:
+ * ```ts,runnable,console
+ * import { QuadraticBezier, Vec2 } from '@js-draw/math';
+ *
+ * const startPoint = Vec2.of(4, 3);
+ * const controlPoint = Vec2.of(1, 1);
+ * const endPoint = Vec2.of(1, 3);
+ *
+ * const curve = new QuadraticBezier(
+ *   startPoint,
+ *   controlPoint,
+ *   endPoint,
+ * );
+ *
+ * console.log('Curve:', curve);
+ * ```
+ *
+ * **Note**: Some Bézier operations internally use the `bezier-js` library.
  */
 export class QuadraticBezier extends BezierJSWrapper {
-    constructor(p0, p1, p2) {
+    constructor(
+    // Start point
+    p0, 
+    // Control point
+    p1, 
+    // End point
+    p2) {
         super();
         this.p0 = p0;
         this.p1 = p1;

package/dist/mjs/shapes/Rect2.d.ts

@@ -15,6 +15,18 @@ export interface RectTemplate {
 /**
  * Represents a rectangle in 2D space, parallel to the XY axes.
  *
+ * **Example**:
+ * ```ts,runnable,console
+ * import { Rect2, Vec2 } from '@js-draw/math';
+ *
+ * const rect = Rect2.fromCorners(
+ *   Vec2.of(0, 0),
+ *   Vec2.of(10, 10),
+ * );
+ * console.log('area', rect.area);
+ * console.log('topLeft', rect.topLeft);
+ * ```
+ *
  * `invariant: w ≥ 0, h ≥ 0, immutable`
  */
 export declare class Rect2 extends Abstract2DShape {
@@ -29,6 +41,7 @@ export declare class Rect2 extends Abstract2DShape {
     translatedBy(vec: Vec2): Rect2;
     resizedTo(size: Vec2): Rect2;
     containsPoint(other: Point2): boolean;
+    /** @returns true iff `other` is completely within this `Rect2`. */
     containsRect(other: Rect2): boolean;
     /**
      * @returns true iff this and `other` overlap

package/dist/mjs/shapes/Rect2.mjs

@@ -4,10 +4,30 @@ import  Abstract2DShape  from './Abstract2DShape.mjs';
 /**
  * Represents a rectangle in 2D space, parallel to the XY axes.
  *
+ * **Example**:
+ * ```ts,runnable,console
+ * import { Rect2, Vec2 } from '@js-draw/math';
+ *
+ * const rect = Rect2.fromCorners(
+ *   Vec2.of(0, 0),
+ *   Vec2.of(10, 10),
+ * );
+ * console.log('area', rect.area);
+ * console.log('topLeft', rect.topLeft);
+ * ```
+ *
  * `invariant: w ≥ 0, h ≥ 0, immutable`
  */
 export class Rect2 extends Abstract2DShape {
-    constructor(x, y, w, h) {
+    constructor(
+    // Top left x coordinate
+    x, 
+    // Top left y coordinate
+    y, 
+    // Width
+    w, 
+    // Height
+    h) {
         super();
         this.x = x;
         this.y = y;
@@ -39,6 +59,7 @@ export class Rect2 extends Abstract2DShape {
             this.x + this.w >= other.x &&
             this.y + this.h >= other.y);
     }
+    /** @returns true iff `other` is completely within this `Rect2`. */
     containsRect(other) {
         return (this.x <= other.x &&
             this.y <= other.y &&

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@js-draw/math",
-	"version": "1.22.0",
+	"version": "1.23.1",
 	"description": "A math library for js-draw. ",
 	"types": "./dist/mjs/lib.d.ts",
 	"main": "./dist/cjs/lib.js",
@@ -27,7 +27,7 @@
 		"bezier-js": "6.1.3"
 	},
 	"devDependencies": {
-		"@js-draw/build-tool": "^1.22.0",
+		"@js-draw/build-tool": "^1.23.1",
 		"@types/bezier-js": "4.1.0",
 		"@types/jest": "29.5.5",
 		"@types/jsdom": "21.1.3"
@@ -44,5 +44,5 @@
 		"svg",
 		"math"
 	],
-	"gitHead": "c922cf6e44d078133100e01383ba1bacdebe01bd"
+	"gitHead": "e0bb3336d5f3a94533c823906778d39a4880f4cf"
 }

package/src/Color4.test.ts

@@ -86,4 +86,9 @@ describe('Color4', () => {
 			expect(Color4.contrastRatio(colorA, colorB)).toBeCloseTo(expectedContrast, 1);
 		}
 	});
+
+	it('should support creating colors from an RGBA array', () => {
+		expect(Color4.fromRGBArray([255, 0, 0])).objEq(Color4.ofRGB(1, 0, 0));
+		expect(Color4.fromRGBArray([255, 0, 0, 128])).objEq(Color4.ofRGBA(1, 0, 0, 0.5));
+	});
 });

package/src/Color4.ts

@@ -37,6 +37,10 @@ export class Color4 {
 		return Color4.ofRGBA(red, green, blue, 1.0);
 	}
 
+	/**
+	 * Creates a color from red, green, blue, and transparency components. Each component should
+	 * be in the range $[0, 1]$.
+	 */
 	public static ofRGBA(red: number, green: number, blue: number, alpha: number): Color4 {
 		red = Math.max(0, Math.min(red, 1));
 		green = Math.max(0, Math.min(green, 1));
@@ -46,6 +50,40 @@ export class Color4 {
 		return new Color4(red, green, blue, alpha);
 	}
 
+	/**
+	 * Creates a color from an RGB (or RGBA) array.
+	 *
+	 * This is similar to {@link ofRGB} and {@link ofRGBA}, but, by default, takes values
+	 * that range from 0 to 255.
+	 *
+	 * If the array values instead range from 0-1, pass `maxValue` as `1`.
+	 */
+	public static fromRGBArray(
+		array: Uint8Array | Uint8ClampedArray | number[],
+		maxValue: number = 255,
+	) {
+		const red = array[0];
+		const green = array[1] ?? red;
+		const blue = array[2] ?? red;
+
+		let alpha = 255;
+		if (3 < array.length) {
+			alpha = array[3];
+		}
+
+		return Color4.ofRGBA(red / maxValue, green / maxValue, blue / maxValue, alpha / maxValue);
+	}
+
+	/**
+	 * Creates a `Color4` from a three or four-component hexadecimal
+	 * [color string](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet).
+	 *
+	 * Example:
+	 * ```ts,runnable,console
+	 * import { Color4 } from '@js-draw/math';
+	 * console.log(Color4.fromHex('#ff0'));
+	 * ```
+	 */
 	public static fromHex(hexString: string): Color4 {
 		// Remove starting '#' (if present)
 		hexString = (hexString.match(/^[#]?(.*)$/) ?? [])[1];
@@ -82,7 +120,7 @@ export class Color4 {
 		return Color4.ofRGBA(components[0], components[1], components[2], components[3]);
 	}
 
-	/** Like fromHex, but can handle additional colors if an `HTMLCanvasElement` is available. */
+	/** Like {@link fromHex}, but can handle additional colors if an `HTMLCanvasElement` is available. */
 	public static fromString(text: string): Color4 {
 		if (text.startsWith('#')) {
 			return Color4.fromHex(text);

package/src/Mat33.fromCSSMatrix.test.ts

@@ -2,7 +2,7 @@ import Mat33 from './Mat33';
 import { Vec2 } from './Vec2';
 
 describe('Mat33.fromCSSMatrix', () => {
-	it('should convert CSS matrix(...) strings to matricies', () => {
+	it('should convert CSS matrix(...) strings to matrices', () => {
 		// From MDN:
 		// 		⎡ a c e ⎤
 		// 		⎢ b d f ⎥  =  matrix(a,b,c,d,e,f)

package/src/Mat33.test.ts

@@ -39,7 +39,7 @@ describe('Mat33 tests', () => {
 		expect(M.inverse().rightMul(M)).objEq(Mat33.identity, fuzz);
 	});
 
-	it('90 degree z-rotation matricies should rotate 90 degrees counter clockwise', () => {
+	it('90 degree z-rotation matrices should rotate 90 degrees counter clockwise', () => {
 		const fuzz = 0.001;
 
 		const M = Mat33.zRotation(Math.PI / 2);
@@ -48,7 +48,7 @@ describe('Mat33 tests', () => {
 		expect(M.transformVec2(rotated)).objEq(Vec2.unitX.times(-1), fuzz);
 	});
 
-	it('z-rotation matricies should preserve the given origin', () => {
+	it('z-rotation matrices should preserve the given origin', () => {
 		const testPairs: Array<[number, Vec2]> = [
 			[Math.PI / 2, Vec2.zero],
 			[-Math.PI / 2, Vec2.zero],
@@ -60,7 +60,7 @@ describe('Mat33 tests', () => {
 		}
 	});
 
-	it('translation matricies should translate Vec2s', () => {
+	it('translation matrices should translate Vec2s', () => {
 		const fuzz = 0.01;
 
 		const M = Mat33.translation(Vec2.of(1, -4));
@@ -68,7 +68,7 @@ describe('Mat33 tests', () => {
 		expect(M.transformVec2(Vec2.of(-1, 3))).objEq(Vec2.of(0, -1), fuzz);
 	});
 
-	it('scaling matricies should scale about the provided center', () => {
+	it('scaling matrices should scale about the provided center', () => {
 		const fuzz = 0.01;
 
 		const center = Vec2.of(1, -4);
@@ -77,14 +77,14 @@ describe('Mat33 tests', () => {
 		expect(M.transformVec2(Vec2.of(0, 0))).objEq(Vec2.of(-1, 4), fuzz);
 	});
 
-	it('calling inverse on singular matricies should result in the identity matrix', () => {
+	it('calling inverse on singular matrices should result in the identity matrix', () => {
 		const fuzz = 0.001;
 		const singularMat = Mat33.ofRows(Vec3.of(0, 0, 1), Vec3.of(0, 1, 0), Vec3.of(0, 1, 1));
 		expect(singularMat.invertable()).toBe(false);
 		expect(singularMat.inverse()).objEq(Mat33.identity, fuzz);
 	});
 
-	it('z-rotation matricies should be invertable', () => {
+	it('z-rotation matrices should be invertable', () => {
 		const fuzz = 0.01;
 		const M = Mat33.zRotation(-0.2617993877991494, Vec2.of(481, 329.5));
 		expect(M.inverse().transformVec2(M.transformVec2(Vec2.unitX))).objEq(Vec2.unitX, fuzz);

package/src/Mat33.ts

@@ -440,6 +440,26 @@ export class Mat33 {
 		return new Mat33(1, 0, amount.x, 0, 1, amount.y, 0, 0, 1);
 	}
 
+	/**
+	 * Creates a matrix for rotating `Vec2`s about `center` by some number of `radians`.
+	 *
+	 * For this function, {@link Vec2}s are considered to be points in 2D space.
+	 *
+	 * For example,
+	 * ```ts,runnable,console
+	 * import { Mat33, Vec2 } from '@js-draw/math';
+	 *
+	 * const halfCircle = Math.PI; // PI radians = 180 degrees = 1/2 circle
+	 * const center = Vec2.of(1, 1); // The point (1,1)
+	 * const rotationMatrix = Mat33.zRotation(halfCircle, center);
+	 *
+	 * console.log(
+	 *   'Rotating (0,0) 180deg about', center, 'results in',
+	 *   // Rotates (0,0)
+	 *   rotationMatrix.transformVec2(Vec2.zero),
+	 * );
+	 * ```
+	 */
 	public static zRotation(radians: number, center: Point2 = Vec2.zero): Mat33 {
 		if (radians === 0) {
 			return Mat33.identity;

package/src/Vec3.ts

@@ -168,7 +168,7 @@ export interface Vec3 {
 	asArray(): [number, number, number];
 
 	/**
-	 * [fuzz] The maximum difference between two components for this and [other]
+	 * @param tolerance The maximum difference between two components for this and [other]
 	 * to be considered equal.
 	 *
 	 * @example
@@ -481,12 +481,16 @@ class Vec2Impl implements Vec3 {
 }
 
 /**
- * A `Vec2` is a `Vec3` optimized for working in a plane. As such, they have an
+ * A `Vec2` is a {@link Vec3} optimized for working in a plane. `Vec2`s have an
  * always-zero `z` component.
  *
  * ```ts,runnable,console
  * import { Vec2 } from '@js-draw/math';
- * console.log(Vec2.of(1, 2));
+ *
+ * const v = Vec2.of(1, 2);
+ * console.log('a Vec2:', v);
+ * console.log('x component:', v.x);
+ * console.log('z component:', v.z);
  * ```
  */
 export namespace Vec2 {
@@ -527,6 +531,7 @@ export namespace Vec2 {
 	export const zero = Vec2.of(0, 0);
 }
 
+/** Contains static methods for constructing a {@link Vec3}. */
 export namespace Vec3 {
 	/**
 	 * Construct a vector from three components.
@@ -535,6 +540,7 @@ export namespace Vec3 {
 	 * ```ts,runnable,console
 	 * import { Vec3 } from '@js-draw/math';
 	 * const v1 = Vec3.of(1, 2, 3);
+	 * console.log(v1.plus(Vec3.of(0, 100, 0)));
 	 * ```
 	 */
 	export const of = (x: number, y: number, z: number): Vec3 => {
@@ -545,8 +551,11 @@ export namespace Vec3 {
 		}
 	};
 
+	/** A unit vector in the x direction (`[1, 0, 0]`). */
 	export const unitX = Vec2.unitX;
+	/** A unit vector in the y direction (`[0, 1, 0]`). */
 	export const unitY = Vec2.unitY;
+	/** The zero vector (`[0, 0, 0]`). */
 	export const zero = Vec2.zero;
 
 	/** A vector of length 1 in the z direction. */

package/src/lib.ts

@@ -1,4 +1,7 @@
 /**
+ * This package contains general math utilities used by `js-draw`.
+ * These include 2D and 3D vectors, 2D paths, and 3x3 matrices.
+ *
  * ```ts,runnable,console
  * import { Vec2, Mat33, Rect2 } from '@js-draw/math';
  *

package/src/shapes/BezierJSWrapper.ts

@@ -56,6 +56,7 @@ export abstract class BezierJSWrapper extends Parameterized2DShape {
 		return Vec2.ofXY(this.getBezier().get(t));
 	}
 
+	/** @returns the curve's directional derivative at `t`. */
 	public derivativeAt(t: number): Point2 {
 		return Vec2.ofXY(this.getBezier().derivative(t));
 	}
@@ -64,6 +65,7 @@ export abstract class BezierJSWrapper extends Parameterized2DShape {
 		return Vec2.ofXY((this.getBezier() as any).dderivative(t));
 	}
 
+	/** @returns the [normal vector](https://en.wikipedia.org/wiki/Normal_(geometry)) to this curve at `t`. */
 	public normal(t: number): Vec2 {
 		return Vec2.ofXY(this.getBezier().normal(t));
 	}

package/src/shapes/Path.ts

@@ -11,6 +11,7 @@ import Parameterized2DShape from './Parameterized2DShape';
 import BezierJSWrapper from './BezierJSWrapper';
 import convexHull2Of from '../utils/convexHull2Of';
 
+/** Identifiers for different path commands. These commands can make up a {@link Path}. */
 export enum PathCommandType {
 	LineTo,
 	MoveTo,

package/src/shapes/QuadraticBezier.ts

@@ -4,14 +4,34 @@ import BezierJSWrapper from './BezierJSWrapper';
 import Rect2 from './Rect2';
 
 /**
- * Represents a 2D Bézier curve.
+ * Represents a 2D [Bézier curve](https://en.wikipedia.org/wiki/B%C3%A9zier_curve).
  *
- * **Note**: Many Bézier operations use `bezier-js`'s.
+ * Example:
+ * ```ts,runnable,console
+ * import { QuadraticBezier, Vec2 } from '@js-draw/math';
+ *
+ * const startPoint = Vec2.of(4, 3);
+ * const controlPoint = Vec2.of(1, 1);
+ * const endPoint = Vec2.of(1, 3);
+ *
+ * const curve = new QuadraticBezier(
+ *   startPoint,
+ *   controlPoint,
+ *   endPoint,
+ * );
+ *
+ * console.log('Curve:', curve);
+ * ```
+ *
+ * **Note**: Some Bézier operations internally use the `bezier-js` library.
  */
 export class QuadraticBezier extends BezierJSWrapper {
 	public constructor(
+		// Start point
 		public readonly p0: Point2,
+		// Control point
 		public readonly p1: Point2,
+		// End point
 		public readonly p2: Point2,
 	) {
 		super();

package/src/shapes/Rect2.ts

@@ -17,6 +17,18 @@ export interface RectTemplate {
 /**
  * Represents a rectangle in 2D space, parallel to the XY axes.
  *
+ * **Example**:
+ * ```ts,runnable,console
+ * import { Rect2, Vec2 } from '@js-draw/math';
+ *
+ * const rect = Rect2.fromCorners(
+ *   Vec2.of(0, 0),
+ *   Vec2.of(10, 10),
+ * );
+ * console.log('area', rect.area);
+ * console.log('topLeft', rect.topLeft);
+ * ```
+ *
  * `invariant: w ≥ 0, h ≥ 0, immutable`
  */
 export class Rect2 extends Abstract2DShape {
@@ -28,9 +40,13 @@ export class Rect2 extends Abstract2DShape {
 	public readonly area: number;
 
 	public constructor(
+		// Top left x coordinate
 		public readonly x: number,
+		// Top left y coordinate
 		public readonly y: number,
+		// Width
 		public readonly w: number,
+		// Height
 		public readonly h: number,
 	) {
 		super();
@@ -69,6 +85,7 @@ export class Rect2 extends Abstract2DShape {
 		);
 	}
 
+	/** @returns true iff `other` is completely within this `Rect2`. */
 	public containsRect(other: Rect2): boolean {
 		return (
 			this.x <= other.x &&