Merge pull request #17 from nberlette/docs/module-docs

docs: improve module doc comments

Author: nberlette

deno.lock

@@ -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/abs.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/acos.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/acosh.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/asin.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/asinh.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/atan.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/atan2.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/atanh.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";