flocc 0.5.18 → 0.5.21

package/dist/helpers/Vector.d.ts

@@ -1,54 +1,157 @@
 /// <reference path="../src/types/Point.d.ts" />
 /**
+ * A `Vector` contains multi-dimensional numeric data.
+ *
  * @since 0.1.0
  */
 declare class Vector implements Point {
     data: Array<number>;
+    /**
+     * The dimension of this `Vector`, or the last index that has a value (plus one).
+     *
+     * ```js
+     * const a = new Vector(1, 1, 1);
+     * a.dimension; // 3
+     *
+     * const b = new Vector(1, 2, 3, 4, 5);
+     * b.dimension; // 5
+     * ```
+     *
+     * Dimensions can be dynamically updated after a `Vector` is created:
+     *
+     * ```js
+     * const v = new Vector(0);
+     * v.dimension; // 1
+     *
+     * v.set(3, 10);
+     * v.dimension; // 4 (indices start at 0)
+     * ```
+     *
+     *  */
     dimension: number;
     constructor(...data: Array<number>);
     /**
+     * Retrieve a value from a `Vector` by its index. If the given index is greater than the
+     * `Vector`'s dimension, this returns `0` by default.
+     *
+     * ```js
+     * const v = new Vector(1, 2, 4);
+     *
+     * v.index(0); // returns 1
+     * v.index(2); // returns 4
+     * v.index(5); // returns 0
+     * ```
      * @since 0.1.0
      */
-    index(n: number): number;
+    index(i: number): number;
     /**
-     * Overwrite the value at a given index or position. If the index is beyond the dimension of this vector,
-     * the dimension will be increased to the dimensionality implied by the index.
-     * @param i {number | string} - The numerical index (0-based) or lowercase string value ('x') to set.
-     * @param value {number} - The value to set at this index/position.
+     * Set the value at a given index. If the index is greater than the {@linkcode dimension}
+     * of this `Vector`, the dimension will be increased to the dimensionality implied by the index.
+     * @param i The numerical index (0-based) or lowercase string value (e.g. `"x"`) to set.
+     * @param value The value to set at this index/position.
+     *
+     * ```js
+     * const vector = new Vector();
+     * vector.set(0, 10);
+     * vector.set('y', 2);
+     * vector.set(2, 4);
+     *
+     * vector.xyz; // [10, 2, 4]
+     * ```
+     *
      * @since 0.1.0
      */
-    set(i: number | string, value: number): this;
+    set(i: number | "x" | "y" | "z" | "w" | "r" | "g" | "b" | "a", value: number): this;
+    /** @since 0.1.0 */
     get x(): number;
+    /** @since 0.1.0 */
     get y(): number;
+    /** @since 0.1.0 */
     get z(): number;
+    /** @since 0.1.0 */
     get w(): number;
-    get xy(): Array<number>;
-    get xz(): Array<number>;
-    get yz(): Array<number>;
-    get xyz(): Array<number>;
+    /** @since 0.2.4 */
+    get xy(): [number, number];
+    /** @since 0.2.4 */
+    get xz(): [number, number];
+    /** @since 0.2.4 */
+    get yz(): [number, number];
+    /** @since 0.2.4 */
+    get xyz(): [number, number, number];
+    /**
+     * `r` for 'red' (the 1st value)
+     * @since 0.1.0
+     */
     get r(): number;
+    /**
+     * `g` for 'green' (the 2nd value)
+     * @since 0.1.0
+     */
     get g(): number;
+    /**
+     * `b` for 'blue' (the 3rd value)
+     * @since 0.1.0
+     */
     get b(): number;
+    /**
+     * `a` for 'alpha' (the 4th value)
+     * @since 0.1.0
+     */
     get a(): number;
-    get rgb(): Array<number>;
-    get rgba(): Array<number>;
+    /** @since 0.2.4 */
+    get rgb(): [number, number, number];
+    /** @since 0.2.4 */
+    get rgba(): [number, number, number, number];
+    /** @since 0.1.0 */
     set x(n: number);
+    /** @since 0.1.0 */
     set y(n: number);
+    /** @since 0.1.0 */
     set z(n: number);
+    /** @since 0.1.0 */
     set w(n: number);
+    /**
+     * `r` for 'red' (the 1st value)
+     * @since 0.1.0
+     */
     set r(n: number);
+    /**
+     * `g` for 'green' (the 2nd value)
+     * @since 0.1.0
+     */
     set g(n: number);
+    /**
+     * `b` for 'blue' (the 3rd value)
+     * @since 0.1.0
+     */
     set b(n: number);
+    /**
+     * `a` for 'alpha' (the 4th value)
+     * @since 0.1.0
+     */
     set a(n: number);
     /**
+     * Add another `Vector` to this `Vector`. This *does* mutate the `Vector` that calls this method.
      * @since 0.1.0
      */
     add(v: Vector): this;
     /**
+     * Multiply this `Vector` by a scalar number. This *does* mutate the `Vector` that calls this method.
+     *
+     * ```js
+     * const v = new Vector(1, 2);
+     * v.multiplyScalar(5);
+     * v.xy; // returns [5, 10]
+     *
+     * v.multiplyScalar(-0.5);
+     * v.xy; // returns [-2.5, -5]
+     * ```
+     *
      * @since 0.1.0
      */
     multiplyScalar(n: number): this;
     /**
+     * Add a scalar number to all of this `Vector`'s values'. This *does* mutate the `Vector` that calls this method.
      * @since 0.1.0
      */
     addScalar(n: number): this;
@@ -58,32 +161,58 @@ declare class Vector implements Point {
      */
     length(): number;
     /**
-     * Normalize the vector (turn it into a vector with length = 1).
-     * Has no effect on the 0 vector.
+     * Normalize the `Vector` (turn it into a `Vector` with length = `1`). Has no effect on the 0 `Vector`. This *does* mutate the `Vector` that calls this method.
+     *
+     * ```js
+     * const v = new Vector(5, 3, -1);
+     * v.normalize();
+     * v.length(); // returns 1
+     * ```
+     *
      * @since 0.1.0
      */
     normalize(): this;
     /**
+     * Create a copy of this `Vector`.
      * @since 0.1.0
      */
     clone(): Vector;
     /**
-     * Rotate a vector about the Z axis.
-     * @param angle {number} - The angle by which to rotate the vector, in radians
+     * Rotate the `Vector` about the z-axis by `angle` radians (updating its `x` and `y` values). This *does* mutate the `Vector` that calls this method.
+     *
+     * ```js
+     * const v = new Vector(1, 0);
+     * v.rotateZ(Math.PI / 2); // rotate by PI / 2 radians = 90 degrees
+     *
+     * v.xy; // returns [0, 1]
+     * ```
+     *
      * @since 0.2.2
      */
     rotateZ(angle: number): this;
     /**
-     * Get the dot product of this vector with another.
-     * @param {Vector} v - The other vector.
+     * Get the {@link https://en.wikipedia.org/wiki/Dot_product | dot product} of this `Vector` with another.
+     * @since 0.2.4
      */
     dot(v: Vector): number;
     /**
-     * Linearly interpolate between this vector and another vector.
-     * Note that this method returns a new vector and does not mutate the vector on which it is called!
-     * @param {Vector} v - The other vector.
-     * @param {number} t - The amount by which to interpolate.
+     * Linearly interpolate between this `Vector` and another `Vector`. This *does not* mutate the original `Vector` that calls this method, but returns a new `Vector`.
+     *
+     * ```js
+     * const a = new Vector(1, 3, -5);
+     * const b = new Vector(4, -2);
+     *
+     * a.lerp(b, 0); // returns a clone of Vector a
+     * a.lerp(b, 1); // returns a clone of Vector b
+     *
+     * const mid = a.lerp(b, 0.5); // returns a Vector halfway between a and b
+     * mid.xyz; // returns [2.5, 0.5, -2.5]
+     * ```
+     *
+     * @param v - The other vector.
+     * @param t - The amount by which to interpolate (usually between `0` and `1`, although it can be any number).
      * @returns {Vector} - The new, interpolated vector.
+     * @since 0.2.4
      */
     lerp(v: Vector, t: number): Vector;
 }

package/dist/renderers/ASCIIRenderer.d.ts

@@ -1,15 +1,44 @@
 import { GridEnvironment } from "../environments/GridEnvironment";
 import { AbstractRenderer } from "./AbstractRenderer";
 /**
+ * An `ASCIIRenderer` renders the {@link Agent | `Agent`}s in
+ * a {@linkcode GridEnvironment}. `Agent`s are rendered
+ * using their `"value"` data (a single character).
+ * Since v0.4.0, this class has been **deprecated**, and it will be removed
+ * entirely in v0.6.0.
+ * ```js
+ * const renderer = new ASCIIRenderer(grid);
+ * renderer.mount("#container-id");
+ * ```
+ * @deprecated since 0.4.0
  * @since 0.0.10
  */
 declare class ASCIIRenderer extends AbstractRenderer {
-    /** @member GridEnvironment */
+    /**
+     * @hidden
+     * @override
+     */
+    width: null;
+    /**
+     * @hidden
+     * @override
+     */
+    height: null;
+    /**
+     * Points to the {@linkcode GridEnvironment} that this
+     * `ASCIIRenderer` is tied to. This is automatically set when the
+     * `ASCIIRenderer` is created.
+     */
     environment: GridEnvironment;
-    /** @member HTMLPreElement */
+    /** @hidden */
     pre: HTMLPreElement;
-    constructor(environment: GridEnvironment, opts?: Object);
     /**
+     * Create a new `ASCIIRenderer` by passing in the
+     * {@linkcode GridEnvironment} you want to be rendered.
+     */
+    constructor(environment: GridEnvironment);
+    /**
+     * Renders the contents of the `ASCIIRenderer`'s {@linkcode GridEnvironment}.
      * @since 0.0.10
      */
     render(): void;

package/dist/renderers/AbstractRenderer.d.ts

@@ -1,15 +1,30 @@
 import type { Environment } from "../environments/Environment";
 declare class AbstractRenderer {
-    /** @member Environment */
+    /**
+     * Points to the {@linkcode Environment} that this
+     * renderer is tied to. This is automatically set when the
+     * renderer is created.
+     */
     environment: Environment;
+    /** @hidden */
     canvas: HTMLCanvasElement;
+    /** @hidden */
     context: CanvasRenderingContext2D;
     width: number;
     height: number;
     render(): void;
     /**
      * Mount this renderer to a DOM element. Pass either a string representing a
-     * CSS selector matching the element (i.e. `"#element-id") or the element itself.
+     * CSS selector matching the element or the element itself.
+     *
+     * ```js
+     * // mounts the renderer to the element with the ID `container`
+     * renderer.mount('#container');
+     *
+     * // mounts the renderer to the element itself
+     * const container = document.getElementById('container');
+     * renderer.mount(container);
+     * ```
      * @param {string | HTMLElement} el
      */
     mount(el: string | HTMLElement): void;

package/dist/renderers/CanvasRenderer.d.ts

@@ -2,16 +2,71 @@
 import { AbstractRenderer } from "./AbstractRenderer";
 import type { Environment } from "../environments/Environment";
 /**
+ * A `CanvasRenderer` renders an {@linkcode Environment} spatially in two dimensions.
+ * Importantly, it expects that all {@linkcode Agent}s in the `Environment`
+ * have numeric `"x"` and `"y"` values associated with them.
+ *
+ * `CanvasRenderer`s will render all `Agent`s that are visible in the rendered `Environment` space,
+ * with the color of their `"color"` value (defaulting to black).
+ * Depending on the `"shape"` of the `Agent`, additional data might be needed. `Agent` `"shape"`s can be:
+ * - `"circle"` (default) — Draws a circle centered at the `Agent`'s `"x"` / `"y"` values.
+ *   - If the `Agent` has a `"size"` value, uses that for the circle radius (defaults to 1px).
+ * - `"arrow"` — Draws an arrow centered at the `Agent`'s `"x"` / `"y"` values.
+ *   - The arrow will point in the direction of the `Agent`s `"vx"` / `"vy"` values. For example, an `Agent` with `"vx" = 1` and `"vy" = 0` will be rendered as an arrow pointing to the right.
+ *   - Also uses the `"size" value.
+ * - `"rect"` — Draws a rectangle with the upper-left corner at `"x"` / `"y"`.
+ *   - Uses the `Agent`'s `"width"` and `"height"` values for the dimensions of the rectangle.
+ * - `"triangle"` — Draws a triangle centered at the `Agent`'s `"x"` / `"y"` values.
+ *   - Also uses the `"size"` value.
+ *
  * @since 0.0.11
  */
 declare class CanvasRenderer extends AbstractRenderer {
+    /** @hidden */
     opts: CanvasRendererOptions;
+    /** @hidden */
     buffer: HTMLCanvasElement;
+    /** @hidden */
     terrainBuffer: HTMLCanvasElement;
+    /**
+     * The first parameter must be the {@linkcode Environment} that this
+     * `CanvasRenderer` will render.
+     *
+     * The second parameter specifies options, which can include:
+     * - `autoPosition` (*boolean* = `false`) — For `Environment`s using a {@linkcode Network}, whether to automatically position the `Agent`s.
+     * - `background` (*string* = `"transparent"`) — The background color to draw before rendering any `Agent`s.
+     * - `connectionColor` (*string* = `"black"`) — For `Environment`s using a `Network`, the color of lines
+     * - `connectionOpacity` (*number* = `1`) — For `Environment`s using a `Network`, the opacity of lines
+     * - `connectionWidth` (*number* = `1`) — For `Environment`s using a `Network`, the width of lines
+     * - `height` (*number* = `500`) — The height, in pixels, of the canvas on which to render
+     * - `origin` (*{ x: number; y: number }* = `{ x: 0, y: 0 }`) — The coordinate of the upper-left point of the space to be rendered
+     * - `scale` (*number* = `1`) — The scale at which to render (the larger the scale, the smaller the size of the space that is actually rendered)
+     * - `trace` (*boolean* = `false`) — If `true`, the renderer will not clear old drawings, causing the `Agent`s to appear to *trace* their paths across space
+     * - `width` (*number* = `500`) — The width, in pixels, of the canvas on which to render
+     */
     constructor(environment: Environment, opts: CanvasRendererOptions);
+    /** @hidden */
     x(v: number): number;
+    /** @hidden */
     y(v: number): number;
+    /** @hidden */
     createCanvas(): HTMLCanvasElement;
+    /** @hidden */
+    drawPath(points: [number, number][], dx?: number, dy?: number): void;
+    /** @hidden */
+    drawPathWrap(points: [number, number][]): void;
+    /** @hidden */
+    drawCircle(x: number, y: number, r: number): void;
+    /** @hidden */
+    drawCircleWrap(x: number, y: number, size: number): void;
+    /**
+     * Draw a rectangle centered at (x, y). Automatically calculates the offset
+     * for both width and height.
+     * @hidden
+     */
+    drawRect(x: number, y: number, width: number, height: number): void;
+    /** @hidden */
+    drawRectWrap(x: number, y: number, w: number, h: number): void;
     render(): void;
 }
 export { CanvasRenderer };

package/dist/renderers/Heatmap.d.ts

@@ -2,10 +2,7 @@
 /// <reference path="../src/types/NRange.d.ts" />
 import { AbstractRenderer } from "./AbstractRenderer";
 import type { Environment } from "../environments/Environment";
-interface HeatmapAxis extends NRange {
-    buckets: number;
-    key: string;
-}
+import type HeatmapAxis from "../types/HeatmapAxis";
 interface HeatmapOptions {
     x: string | HeatmapAxis;
     y: string | HeatmapAxis;
@@ -17,34 +14,82 @@ interface HeatmapOptions {
     scale: "relative" | "fixed";
 }
 /**
+ * A `Heatmap` can be used to visualize the distribution of {@linkcode Agent}s across two metrics.
+ * While {@linkcode Histogram}s are useful for showing the distribution of `Agent`s along a single metric
+ * (or on multiple metrics using the same scale), a `Heatmap` can show how two metrics relate to one another &mdash;
+ * correlation, inverse correlation, in a nonlinear manner, randomly (no correlation), etc.
+ *
+ * <img src="https://cms.flocc.network/wp-content/uploads/2020/11/heatmap-basic.png" />
+ *
+ * Note above that, although the output appears similar to what a {@linkcode CanvasRenderer} might output, the `y` axis is reversed here &mdash; low values are at the bottom and high at the top, whereas on a `CanvasRenderer` high values are at the bottom and low at the top.
+ *
  * @since 0.5.8
  */
 declare class Heatmap extends AbstractRenderer {
+    /** @hidden */
     opts: HeatmapOptions;
     width: number;
     height: number;
+    /** @hidden */
     buckets: number[];
+    /** @hidden */
     localMax: number;
+    /** @hidden */
     lastUpdatedScale: Date;
+    /**
+     * The first parameter must be the {@linkcode Environment} that this
+     * `Heatmap` will render.
+     *
+     * The second parameter specifies options, which can include:
+     * - `from` (*string* = `"white"`) &mdash; The color (name, hex value, or RGB) to draw when a cell contains `0` {@linkcode Agent}s
+     * - `to` (*string* = `"black"`) &mdash; The color (name, hex value, or RGB) to draw when a cell contains the highest number of `Agent`s
+     * - `x` and `y` can be either:
+     *   - *string* = `"x"`/`"y"` respectively &mdash; The name of `Agent` data to measure along the `x`/`y` axis
+     *   - *{ buckets: number; key: string; min: number; max: number }* = `{ buckets: 10, key: 'x' | 'y', min: 0, max: 1 }` &mdash; Include the number of buckets to divide the range `min → max` into, along with the name of `Agent` data
+     * - `width` (*number* = `500`) &mdash; The width, in pixels, of the canvas on which to render
+     * - `height` (*number* = `500`) &mdash; The height, in pixels, of the canvas on which to render
+     * - `scale` (either `"relative"` or `"fixed"`, defaults to `"relative"`)
+     *   - `"relative"` &mdash; The maximum number of `Agent`s in any single cell is automatically used as the highest value in the scale. This updates over time based on `Agent` distribution.
+     *   - `"fixed"` &mdash; You supply the number to use as the maximum value (see `max` below).
+     * - `max` (optional, *number*) &mdash; If you use `scale = "fixed"`, then setting a `max` will cause cells with that number (or higher) of `Agent`s to be drawn using the `to` color.
+     *
+     * ```js
+     * // plots the correlation between age of agents (on the x-axis)
+     * // vs. their wealth (on the y-axis)
+     * const heatmap = new Heatmap(environment, {
+     *   x: 'age',
+     *   y: 'wealth'
+     * });
+     * ```
+     */
     constructor(environment: Environment, opts?: HeatmapOptions);
     /**
      * Map a value (on the range x-min to x-max) onto canvas space to draw it along the x-axis.
-     * @param value
+     * @hidden
      */
     x(value: number): number;
     /**
      * Map a value (on the range y-min to y-max) onto canvas space to draw it along the y-axis.
-     * @param value
+     * @hidden
      */
     y(value: number): number;
+    /** @hidden */
     getKey(axis: "x" | "y"): string;
+    /** @hidden */
     getBuckets(axis: "x" | "y"): number;
+    /** @hidden */
     getMin(axis: "x" | "y"): number;
+    /** @hidden */
     getMax(axis: "x" | "y"): number;
+    /** @hidden */
     drawMarkers(): void;
+    /** @hidden */
     updateScale(): void;
+    /** @hidden */
     drawRectangles(): void;
+    /** @hidden */
     resetBuckets(): void;
+    /** @hidden */
     updateBuckets(): void;
     render(): void;
 }

package/dist/renderers/TableRenderer.d.ts

@@ -12,27 +12,119 @@ interface TableRendererOptions {
     type?: "csv" | "table";
 }
 /**
+ * A `TableRenderer` renders an HTML table (for browsers only) or CSV (comma-separated value)
+ * representation of {@linkcode Agent} data.
+ *
+ * ```js
+ * for (let i = 0; i < 3; i++) {
+ *   environment.addAgent(new Agent({
+ *     x: i * 10,
+ *     y: i - 2
+ *   }));
+ * }
+ *
+ * const renderer = new TableRenderer(environment);
+ * renderer.columns = ['x', 'y'];
+ * renderer.mount('#container');
+ * environment.tick();
+ * ```
+ *
+ * The `TableRenderer` renders:
+ *
+ * |x   |y   |
+ * |----|----|
+ * |0   |-2  |
+ * |10  |-1  |
+ * |20  |0   |
+ *
  * @since 0.5.0
  */
 export declare class TableRenderer extends AbstractRenderer {
+    /**
+     * The `TableRenderer`s `columns` should be an array of the keys of `Agent`
+     * data that you want to render.
+     *
+     * ```js
+     * // Suppose Agents in the Environment have data that looks like:
+     * // {
+     * //   "favor": number,
+     * //   "oppose": number,
+     * //   "neutral" number
+     * // }
+     *
+     * // order of columns is determined by order in the array
+     * renderer.columns = ['neutral', 'favor', 'oppose'];
+     * ```
+     *
+     */
     columns: string[];
-    environment: Environment;
+    /** @hidden */
     lastRendered: number;
+    /** @hidden */
     opts: TableRendererOptions;
+    /** @hidden */
     table: Element;
+    /**
+     * The first parameter must be the {@linkcode Environment} that this
+     * `TableRenderer` will render.
+     *
+     * The second parameter specifies options, which can include:
+     * - `"type"` (`"csv"` | `"table"` = `"table"`) &mdash; Whether to render output in CSV or HTML `<table>` format
+     * - `"filter"` &mdash; Include a function (`Agent` => `boolean`) to specify which rows to include in the output. For example, if you only want to include `Agent`s with an x value greater than 100:
+     *   ```js
+     *   const renderer = new TableRenderer(environment, {
+     *     filter: agent => {
+     *       return agent.get('x') > 100;
+     *     }
+     *   });
+     *   ```
+     * - `"limit"` (*number* = `Infinity`) &mdash; The maximum number of rows (`Agent`s) to render. If using a `filter` function, applies the `limit` *after* filtering.
+     * - `"sortKey"` (*string* = `null`) &mdash; Sort the `Agent` data by this key of data
+     * - `"order"` (`"asc"` | `"desc"` = `"desc"`) &mdash; When using a `"sortKey"`, specify whether `Agent`s should be listed in *asc*ending or *desc*ending order
+     * - `"precision"` (*number* = `3`) &mdash; For floating point values, the number of decimal places to display
+     * - `"refresh"` (*number* = `500`) &mdash; The number of milliseconds that should elapse between re-rendering (if this happens too quickly the effect can be visually jarring)
+     */
     constructor(environment: Environment, options?: TableRendererOptions);
     /**
      * Mount this renderer to a DOM element. Pass either a string representing a
-     * CSS selector matching the element (i.e. `"#element-id") or the element itself.
+     * CSS selector matching the element or the element itself.
+     *
+     * ```js
+     * // mounts the renderer to the element with the ID `container`
+     * renderer.mount('#container');
+     *
+     * // mounts the renderer to the element itself
+     * const container = document.getElementById('container');
+     * renderer.mount(container);
+     * ```
      * @override
      * @param {string | HTMLElement} el
      */
     mount(el: string | HTMLElement): void;
+    /** @hidden */
     serializeColumns(joiner: string, start?: string, end?: string, escape?: boolean): string;
+    /** @hidden */
     serializeRows(cellJoiner: string, rowJoiner: string, start?: string, end?: string, rowStart?: string, rowEnd?: string, escape?: boolean): string;
+    /** @hidden */
     renderCSV(): string;
+    /** @hidden */
     renderHTMLTable(): string;
     /**
+     * Returns the outer HTML of the table or the CSV data as a string. This can be useful for exporting data, particularly in a Node.js environment as opposed to in a browser. For instance, in a Node.js script, you could write the CSV data to a file as follows:
+     *
+     * ```js
+     * const fs = require('fs'); // import the file system module
+     *
+     * const environment = new Environment();
+     * for (let i = 0; i < 3; i++) environment.addAgent(new Agent({ i }));
+     *
+     * const renderer = new TableRenderer(environment, { type: 'csv' });
+     * renderer.columns = ['i'];
+     *
+     * // write the TableRenderer's output to a CSV file named data.csv
+     * fs.writeFileSync('./data.csv', renderer.output());
+     * ```
+     *
      * @since 0.5.0
      */
     output(): string;

package/dist/types/HeatmapAxis.d.ts

@@ -0,0 +1,10 @@
+/**
+ * This is the doc comment for file1.ts
+ *
+ * Specify this is a module comment without renaming it:
+ * @module
+ */
+export default interface HeatmapAxis extends NRange {
+    buckets: number;
+    key: string;
+}

package/dist/utils/clamp.d.ts

@@ -1,9 +1,13 @@
 /**
- * Restricts a number x to the range min --> max.
- * @param {number} x
- * @param {number} min
- * @param {number} max
- * @return {number} The clamped value.
+ * Given a `number` and `min` and `max` values, restrict the number
+ * to the range specified.
+ *
+ * ```js
+ * clamp(5, 1, 10); // returns 5
+ * clamp(5, 2, 4); // returns 4
+ * clamp(0, -4, -3); // returns -3
+ * ```
+ *
  * @since 0.0.5
  */
 export default function clamp(x: number, min: number, max: number): number;

package/dist/utils/distance.d.ts

@@ -1,12 +1,21 @@
 /// <reference path="../src/types/Point.d.ts" />
 import { Agent } from "../agents/Agent";
 /**
- * Finds the distance between `p1` and `p2`. The inputs may be plain objects
- * with `x`, `y`, and/or `z` keys, or Agent-like objects who have
- * `x`, `y`, and/or `z` data.
- * @param {Point|Agent} p1
- * @param {Point|Agent} p2
- * @return {number} The distance between p1 and p2.
+ * Finds the distance between `p1` and `p2`.
+ *
+ * The inputs may be plain objects with `x`, `y`, and/or `z` keys, {@linkcode Vector}s,
+ * or {@linkcode Agent}s with `x`, `y`, and/or `z` data.
+ *
+ * ```js
+ * const a1 = new Agent();
+ * const a2 = new Agent({ x: 3, y: 4 });
+ * distance(a1, a2); // returns 5 (defaults to x = 0 and y = 0 for a1)
+ *
+ * const p1 = { x: 0, y: 2 };
+ * const p2 = { x: 0, y: 4 };
+ * distance(p1, p2); // returns 2
+ * ```
+ *
  * @since 0.0.10
  */
 export default function distance(p1: Point | Agent, p2: Point | Agent): number;