docs: improve module doc comments

src/abs.ts

@@ -1,6 +1,13 @@
 /**
  * Performant local implementation of the `Math.abs` function.
  *
+ * @example
+ * ```ts
+ * import { abs } from "@nick/math/abs";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(abs(-3.5), 3.5);
+ * ```
  * @module abs
  */
 

src/acos.ts

@@ -2,6 +2,13 @@
  * Calculates the arccosine (inverse cosine) of a number, returning a value in
  * the range `[0, π]`.
  *
+ * @example
+ * ```ts
+ * import { acos } from "@nick/math/acos";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(acos(1), 0);
+ * ```
  * @module acos
  */
 

src/acosh.ts

@@ -3,6 +3,13 @@
  * the range `[0, +Infinity]`.
  *
  * @category Trigonometry
+ * @example
+ * ```ts
+ * import { acosh } from "@nick/math/acosh";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(acosh(1), 0);
+ * ```
  * @module acosh
  */
 import { NAN } from "./constants/nan.ts";

src/asin.ts

@@ -3,6 +3,13 @@
  * range `[-π/2, π/2]`.
  *
  * @category Trigonometry
+ * @example
+ * ```ts
+ * import { asin } from "@nick/math/asin";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(asin(0), 0);
+ * ```
  * @module asin
  */
 import { NAN } from "./constants/nan.ts";

src/asinh.ts

@@ -1,6 +1,13 @@
 /**
  * Calculates the inverse hyperbolic sine of a number.
  *
+ * @example
+ * ```ts
+ * import { asinh } from "@nick/math/asinh";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(asinh(0), 0);
+ * ```
  * @module asinh
  */
 import { isFinite } from "./guards/finite.ts";

src/atan.ts

@@ -2,6 +2,13 @@
  * Calculates the arctangent (inverse tangent) of a number, returning a value
  * in the range `[-π/2, π/2]`.
  *
+ * @example
+ * ```ts
+ * import { atan } from "@nick/math/atan";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(atan(0), 0);
+ * ```
  * @module atan
  */
 import { abs } from "./abs.ts";

src/atan2.ts

@@ -2,6 +2,13 @@
  * Calculates the arctangent of the quotient of its arguments, `y / x`,
  * returning a value in the range `(-π, π]`.
  *
+ * @example
+ * ```ts
+ * import { atan2 } from "@nick/math/atan2";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(atan2(0, 1), 0);
+ * ```
  * @module atan2
  */
 import { NAN } from "./constants/nan.ts";

src/atanh.ts

@@ -2,6 +2,13 @@
  * Calculates the inverse hyperbolic tangent of a number, returning a value in
  * the range `[-∞, +∞]`.
  *
+ * @example
+ * ```ts
+ * import { atanh } from "@nick/math/atanh";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(atanh(0), 0);
+ * ```
  * @module atanh
  */
 import { isNaN, NAN } from "./guards/nan.ts";

src/cbrt.ts

@@ -1,6 +1,13 @@
 /**
  * Calculates the cube root of a number, handling negative values as well.
  *
+ * @example
+ * ```ts
+ * import { cbrt } from "@nick/math/cbrt";
+ * import assert from "node:assert";
+ *
+ * assert.ok(Math.abs(cbrt(27) - 3) < 1e-12);
+ * ```
  * @module cbrt
  */
 import { abs } from "./abs.ts";

src/ceil.ts

@@ -1,6 +1,13 @@
 /**
  * Performant local implementation of the `Math.ceil` function.
  *
+ * @example
+ * ```ts
+ * import { ceil } from "@nick/math/ceil";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(ceil(1.2), 2);
+ * ```
  * @module ceil
  */
 

src/clamp.ts

@@ -6,6 +6,13 @@
  *
  * **Note**: this is a non-standard utility function.
  *
+ * @example
+ * ```ts
+ * import { clamp } from "@nick/math/clamp";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(clamp(10, 0, 5), 5);
+ * ```
  * @module clamp
  */
 import { max } from "./max.ts";

src/clz32.ts

@@ -3,6 +3,13 @@
  * `Math.clz32` function, which counts the number of leading zero bits in the
  * 32-bit binary representation of a number.
  *
+ * @example
+ * ```ts
+ * import { clz32 } from "@nick/math/clz32";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(clz32(1), 31);
+ * ```
  * @module clz32
  */
 

src/constants/e.ts

@@ -2,6 +2,13 @@
  * This module provides a constant value for the mathematical constant `e` on
  * the runtime value-level, and also the compile-time type-only level.
  *
+ * @example
+ * ```ts
+ * import { E } from "@nick/math/constants/e";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(E, Math.E);
+ * ```
  * @module e
  */
 

src/constants/epsilon.ts

@@ -8,6 +8,13 @@
  * This is approximately equal to `2.220446049250313e-16`, and is provided as a
  * local implementation of the native `Number.EPSILON` constant.
  *
+ * @example
+ * ```ts
+ * import { EPSILON } from "@nick/math/constants/epsilon";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(EPSILON, Number.EPSILON);
+ * ```
  * @module epsilon
  */
 

src/constants/index.ts

@@ -1,6 +1,15 @@
 /**
  * This module re-exports all of the `@nick/math/constants/*` submodules.
  *
+ * @example
+ * ```ts
+ * import { E, PI } from "@nick/math/constants";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(E, Math.E);
+ * assert.strictEqual(PI, Math.PI);
+ * ```
+ * @category Constants
  * @module constants
  */
 export * from "./e.ts";

src/constants/infinity.ts

@@ -1,2 +1,18 @@
+/**
+ * Re-exports the positive and negative infinity constants and their
+ * matching type aliases from the constants submodules.
+ *
+ * @example
+ * ```ts
+ * import { NEGATIVE_INFINITY, POSITIVE_INFINITY } from "@nick/math/constants/infinity";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(POSITIVE_INFINITY, Number.POSITIVE_INFINITY);
+ * assert.strictEqual(NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY);
+ * ```
+ * @category Constants
+ * @module constants/infinity
+ */
+
 export * from "./positive_infinity.ts";
 export * from "./negative_infinity.ts";

src/constants/ln10.ts

@@ -1,9 +1,55 @@
 /**
- * Represents the natural logarithm of `10`, approximately equal to
- * `2.302585092994046`.
+ * This module provides runtime and type-level implementations of the `LN10`
+ * constant found in the native `Math` namespace, which represents the natural
+ * logarithm of the number `10` (approximately equal to `2.302585092994046`).
  *
- * This is a local implementation of the native `Math.LN10` constant.
+ * The `LN10` constant exported by this module can be imported using a standard
+ * named import (i.e., at the _value_ level), or via a type-only import for a
+ * compile-time only reference to the same value.
+ *
+ * @example
+ * ```ts
+ * import { LN10 } from "@nick/math/constants/ln10";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(LN10, 2.302585092994046);
+ * ```
+ * @example
+ * ```ts
+ * import type { LN10 } from "@nick/math/constants/ln10";
+ * import { expectType } from "jsr:@nick/is@0.2.0-rc.6/type/expect";
+ *
+ * expectType<LN10>(2.302585092994046);
+ * ```
+ * @module ln10
+ */
+
+/**
+ * Represents the natural logarithm of the number `10`, approximately equal to
+ * `2.302585092994046`. This corresponds to the native `Math.LN10` constant.
+ * @example
+ * ```ts
+ * import { LN10 } from "@nick/math/constants/ln10";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(LN10, 2.302585092994046);
+ * ```
  * @category Constants
  */
 export const LN10: LN10 = 2.302585092994046;
+
+/**
+ * Type-level alias of the `LN10` constant exported by this module. This allows
+ * `LN10` to be imported using a standard named import (i.e. the _value_ level)
+ * or via type-only import for a compile-time only reference to the same value.
+ *
+ * @example
+ * ```ts
+ * import type { LN10 } from "@nick/math/constants/ln10";
+ * import { expectType } from "jsr:@nick/is@0.2.0-rc.6/type/expect";
+ *
+ * expectType<LN10>(2.302585092994046);
+ * ```
+ * @category Constants
+ */
 export type LN10 = 2.302585092994046;

src/constants/ln2.ts

@@ -1,3 +1,18 @@
+/**
+ * This module provides runtime and type-level implementations of the
+ * `LN2` constant, the natural logarithm of 2.
+ *
+ * @example
+ * ```ts
+ * import { LN2 } from "@nick/math/constants/ln2";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(LN2, Math.LN2);
+ * ```
+ * @category Constants
+ * @module ln2
+ */
+
 /**
  * Represents the natural logarithm of `2`, approximately equal to
  * `0.6931471805599453`.

src/constants/log10e.ts

@@ -1,3 +1,18 @@
+/**
+ * This module provides runtime and type-level implementations of the
+ * `LOG10E` constant, the base-10 logarithm of e.
+ *
+ * @example
+ * ```ts
+ * import { LOG10E } from "@nick/math/constants/log10e";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(LOG10E, Math.LOG10E);
+ * ```
+ * @category Constants
+ * @module log10e
+ */
+
 /**
  * Represents the base-10 logarithm of `e` (Euler's number), approximately
  * equal to `0.4342944819032518`.

src/constants/log2e.ts

@@ -1,3 +1,18 @@
+/**
+ * This module provides runtime and type-level implementations of the
+ * `LOG2E` constant, the base-2 logarithm of e.
+ *
+ * @example
+ * ```ts
+ * import { LOG2E } from "@nick/math/constants/log2e";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(LOG2E, Math.LOG2E);
+ * ```
+ * @category Constants
+ * @module log2e
+ */
+
 /**
  * Represents the base-2 logarithm of `e` (Euler's number), approximately equal
  * to `1.4426950408889634`.

src/constants/max_safe_integer.ts

@@ -1,3 +1,18 @@
+/**
+ * This module provides runtime and type-level implementations of the
+ * `MAX_SAFE_INTEGER` constant, matching `Number.MAX_SAFE_INTEGER`.
+ *
+ * @example
+ * ```ts
+ * import { MAX_SAFE_INTEGER } from "@nick/math/constants/max-safe-integer";
+ * import assert from "node:assert";
+ *
+ * assert.strictEqual(MAX_SAFE_INTEGER, Number.MAX_SAFE_INTEGER);
+ * ```
+ * @category Constants
+ * @module max-safe-integer
+ */
+
 /**
  * Represents the largest integer that can be represented in JavaScript without
  * losing precision, which is approximately equal to `9007199254740991`.