docs: update/clean docstrings in various pkgs

thi-ng · Feb 13, 2025 · 4f6ef52 · 4f6ef52
1 parent 7ad7cc8
commit 4f6ef52
Show file tree

Hide file tree

Showing 168 changed files with 616 additions and 624 deletions.
diff --git a/packages/adjacency/src/mst.ts b/packages/adjacency/src/mst.ts
@@ -19,7 +19,7 @@ import { DisjointSet } from "@thi.ng/disjoint-set";
  * criteria. The result edges will be in ascending order, based on the supplied
  * cost function. The cost function is called once for each edge and return
  * values will be cached prior to sorting (see
- * [`sortByCachedKey()`](https://docs.thi.ng/umbrella/arrays/functions/sortByCachedKey.html)
+ * [`sortByCachedKey`](https://docs.thi.ng/umbrella/arrays/functions/sortByCachedKey.html)
  * for details).
  *
  * References:

diff --git a/packages/api/src/range.ts b/packages/api/src/range.ts
@@ -55,7 +55,7 @@ export type Range32_63 = Range32_47 | Range48_63;
  * Type LUT of allowed range values `[0..n)` for given range size `n`.
  *
  * @example
- * ```
+ * ```text
  * RangeValueMap[4] -> 0 | 1 | 2 | 3
  * ```
  */

diff --git a/packages/arrays/src/binary-search.ts b/packages/arrays/src/binary-search.ts
@@ -15,8 +15,8 @@ import { compareNumAsc } from "@thi.ng/compare/numeric";
  * and each array item (default: identity).
  *
  * The optional `cmp` comparator (default:
- * [`compare()`](https://docs.thi.ng/umbrella/compare/functions/compare.html))
- * is then used to identify the index of `x`. The sort order of `buf` MUST be
+ * [`compare`](https://docs.thi.ng/umbrella/compare/functions/compare.html)) is
+ * then used to identify the index of `x`. The sort order of `buf` MUST be
  * compatible with that of `cmp`.
  *
  * @example
@@ -62,7 +62,7 @@ export const binarySearch = <A, B>(
 /**
  * Similar to {@link binarySearch}, but optimized for numeric arrays and
  * supporting custom comparators (default:
- * [`compareNumAsc()`](https://docs.thi.ng/umbrella/compare/functions/compareNumAsc.html)).
+ * [`compareNumAsc`](https://docs.thi.ng/umbrella/compare/functions/compareNumAsc.html)).
  *
  * @param buf - array
  * @param x - search value

diff --git a/packages/arrays/src/bisect.ts b/packages/arrays/src/bisect.ts
@@ -3,7 +3,7 @@ import type { Predicate, TypedArray } from "@thi.ng/api";
 
 /**
  * Splits array at given index (default: floor(src.length/2)) and returns tuple
- * of [lhs, rhs].
+ * of `[lhs, rhs]`.
  *
  * @param src -
  * @param index -

diff --git a/packages/arrays/src/blit.ts b/packages/arrays/src/blit.ts
@@ -8,7 +8,7 @@ import type { Fn3, Maybe, TypedArray } from "@thi.ng/api";
  * @remarks
  * Where `src` values are the same as `mask`, the corresponding `dest` values
  * will be left unchanged. Performs region clipping, i.e. `dx` can be outside
- * the [0..dest.length) interval.
+ * the `[0,dest.length)` interval.
  *
  * @example
  * ```ts tangle:../export/blit1d.ts

diff --git a/packages/arrays/src/ends-with.ts b/packages/arrays/src/ends-with.ts
@@ -9,7 +9,7 @@ import { equiv as _eq } from "@thi.ng/equiv";
  * be true.
  *
  * By default, uses
- * [`equiv()`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html) for
+ * [`equiv`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html) for
  * equality checking.
  *
  * {@link startsWith}

diff --git a/packages/arrays/src/fill-range.ts b/packages/arrays/src/fill-range.ts
@@ -2,12 +2,12 @@
 import type { NumericArray } from "@thi.ng/api";
 
 /**
- * Fills given array with values in [start .. end) interval from `index`
- * and with optional `step` size.
+ * Fills given array with values in `[start,end)` interval from `index` and with
+ * optional `step` size.
  *
  * @remarks
- * `start` and `end` default to 0 and array length, `step` defaults to 1
- * or -1 (depending on range). Returns array.
+ * `start` and `end` default to 0 and array length, `step` defaults to 1 or -1
+ * (depending on range). Returns array.
  *
  * @example
  * ```ts tangle:../export/fill-range.ts

diff --git a/packages/arrays/src/find.ts b/packages/arrays/src/find.ts
@@ -3,8 +3,9 @@ import type { Predicate2 } from "@thi.ng/api";
 import { equiv as _equiv } from "@thi.ng/equiv";
 
 /**
- * Similar to `Array.find()`, but uses [`equiv()`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html) as
- * default predicate.
+ * Similar to `Array.find()`, but uses
+ * [`equiv`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html) as default
+ * predicate.
  *
  * @param buf - array
  * @param x - search value
@@ -21,8 +22,8 @@ export const find = <T>(
 
 /**
  * Similar to `Array.findIndex()`, but uses
- * [`equiv()`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html) as
- * default predicate.
+ * [`equiv`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html) as default
+ * predicate.
  *
  * @param buf - array
  * @param x - search value

diff --git a/packages/arrays/src/fuzzy-match.ts b/packages/arrays/src/fuzzy-match.ts
@@ -9,13 +9,13 @@ import { equiv as _eq } from "@thi.ng/equiv";
  * @remarks
  * The optional `equiv` predicate can be used to customize item equality
  * checking. Uses
- * [`equiv()`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html) by
+ * [`equiv`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html) by
  * default.
  *
  * Adapted and generalized from: https://github.com/bevacqua/fufuzzyzzysearch
  * (MIT licensed)
  *
- * [`filterFuzzy()`](https://docs.thi.ng/umbrella/transducers/functions/filterFuzzy.html)
+ * [`filterFuzzy`](https://docs.thi.ng/umbrella/transducers/functions/filterFuzzy.html)
  *
  * @param domain - array
  * @param query - search value

diff --git a/packages/arrays/src/insert.ts b/packages/arrays/src/insert.ts
@@ -5,7 +5,7 @@
  *
  * @remarks
  * The function will have no effect iff `i<0` or `i>=k` or `k<1`. If
- * `buf.length` is larger than `k`, only the index range [i..k) will be
+ * `buf.length` is larger than `k`, only the index range `[i,k)` will be
  * modified.
  *
  * In benchmarking with 4, 8, 16, 32, 64 element arrays, this function is

diff --git a/packages/arrays/src/is-sorted.ts b/packages/arrays/src/is-sorted.ts
@@ -5,8 +5,8 @@ import { compare } from "@thi.ng/compare/compare";
 /**
  * Returns true if the given array and its elements in the selected index range
  * (entire array, by default) are in the order defined by the given comparator
- * ([`compare()`](https://docs.thi.ng/umbrella/compare/functions/compare.html)
- * by default).
+ * ([`compare`](https://docs.thi.ng/umbrella/compare/functions/compare.html) by
+ * default).
  *
  * @remarks
  * Always returns true, if effective index range (or array length) has less than

diff --git a/packages/arrays/src/quicksort.ts b/packages/arrays/src/quicksort.ts
@@ -13,7 +13,7 @@ import { swap } from "./swap.js";
  * indices (both inclusive).
  *
  * Uses Hoare partitioning scheme.
- * [`compare()`](https://docs.thi.ng/umbrella/compare/functions/compare.html) is
+ * [`compare`](https://docs.thi.ng/umbrella/compare/functions/compare.html) is
  * used as default comparator and {@link swap} from this package as default swap
  * function. Also see {@link multiSwap}.
  *

diff --git a/packages/arrays/src/starts-with.ts b/packages/arrays/src/starts-with.ts
@@ -9,7 +9,7 @@ import { equiv as _eq } from "@thi.ng/equiv";
  * be true.
  *
  * By default, uses
- * [`equiv()`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html) for
+ * [`equiv`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html) for
  * equality checking.
  *
  * {@link endsWith}

diff --git a/packages/associative/src/api.ts b/packages/associative/src/api.ts
@@ -35,7 +35,7 @@ export interface EquivSetOpts<T> {
 	 * considered equal.
 	 *
 	 * @defaultValue
-	 * [`equiv()`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html)
+	 * [`equiv`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html)
 	 */
 	equiv: Predicate2<T>;
 }
@@ -68,7 +68,7 @@ export interface HashMapOpts<K> {
 	 * Optional key equality predicate.
 	 *
 	 * @defaultValue
-	 * [`equiv()`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html)
+	 * [`equiv`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html)
 	 */
 	equiv?: Predicate2<K>;
 	/**

diff --git a/packages/associative/src/array-set.ts b/packages/associative/src/array-set.ts
@@ -23,7 +23,7 @@ const __vals = (inst: ArraySet<any>) => __private.get(inst)!.vals;
  * customizable equality/equivalence predicate and so is more useful when
  * dealing with structured data. Implements full API of native Set and by the
  * default uses
- * [`equiv()`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html) for
+ * [`equiv`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html) for
  * equivalence checking.
  *
  * Additionally, the type also implements the

diff --git a/packages/associative/src/difference.ts b/packages/associative/src/difference.ts
@@ -28,9 +28,9 @@ export const difference = <T>(a: Set<T>, b: Set<T>, out?: Set<T>): Set<T> => {
 /**
  * Reducer version of {@link difference}. If `src` is given returns the reduced
  * difference of given inputs, else merely returns a reducer to be used with
- * [`reduce()`](https://docs.thi.ng/umbrella/transducers/functions/reduce.html)
+ * [`reduce`](https://docs.thi.ng/umbrella/transducers/functions/reduce.html)
  * /
- * [`transduce()`](https://docs.thi.ng/umbrella/transducers/functions/transduce.html)
+ * [`transduce`](https://docs.thi.ng/umbrella/transducers/functions/transduce.html)
  * functions.
  *
  * @param src - input collections

diff --git a/packages/associative/src/equiv-map.ts b/packages/associative/src/equiv-map.ts
@@ -42,7 +42,7 @@ export class EquivMap<K, V>
 	 * Creates a new instance with optional initial key-value pairs and provided
 	 * options. If no `opts` are given, uses `ArraySet` for storing canonical
 	 * keys and
-	 * [`equiv()`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html) for
+	 * [`equiv`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html) for
 	 * checking key equivalence.
 	 *
 	 * @param pairs - key-value pairs

diff --git a/packages/associative/src/intersection.ts b/packages/associative/src/intersection.ts
@@ -34,9 +34,9 @@ export const intersection = <T>(a: Set<T>, b: Set<T>, out?: Set<T>): Set<T> => {
  * Reducer version of {@link intersection}. If `src` is given returns the
  * reduced intersection of given inputs, else merely returns a reducer to be
  * used with
- * [`reduce()`](https://docs.thi.ng/umbrella/transducers/functions/reduce.html)
+ * [`reduce`](https://docs.thi.ng/umbrella/transducers/functions/reduce.html)
  * /
- * [`transduce()`](https://docs.thi.ng/umbrella/transducers/functions/transduce.html)
+ * [`transduce`](https://docs.thi.ng/umbrella/transducers/functions/transduce.html)
  * functions.
  *
  * @param src - input collections

diff --git a/packages/associative/src/ll-set.ts b/packages/associative/src/ll-set.ts
@@ -24,7 +24,7 @@ const __vals = (inst: LLSet<any>) => __private.get(inst)!.vals;
  * [`DCons`](https://docs.thi.ng/umbrella/dcons/classes/DCons.html) linked list
  * as backing store and a customizable value equality / equivalence predicate.
  * By the default uses
- * [`equiv()`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html) for
+ * [`equiv`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html) for
  * equivalence checking.
  *
  * Additionally, the type also implements the

diff --git a/packages/associative/src/union.ts b/packages/associative/src/union.ts
@@ -25,9 +25,9 @@ export const union = <T>(a: Set<T>, b: Set<T>, out?: Set<T>): Set<T> => {
 /**
  * Reducer version of {@link union}. If `src` is given returns the reduced union
  * of given inputs, else merely returns a reducer to be used with
- * [`reduce()`](https://docs.thi.ng/umbrella/transducers/functions/reduce.html)
+ * [`reduce`](https://docs.thi.ng/umbrella/transducers/functions/reduce.html)
  * /
- * [`transduce()`](https://docs.thi.ng/umbrella/transducers/functions/transduce.html)
+ * [`transduce`](https://docs.thi.ng/umbrella/transducers/functions/transduce.html)
  * functions.
  *
  * @param src - input collections

diff --git a/packages/atom/src/view.ts b/packages/atom/src/view.ts
@@ -136,7 +136,7 @@ export function defViewUnsafe<T = undefined>(
  *
  * Related, the actual value change predicate can be customized. If not given,
  * the default
- * [`equiv()`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html) will be
+ * [`equiv`](https://docs.thi.ng/umbrella/equiv/functions/equiv.html) will be
  * used.
  *
  * @example

diff --git a/packages/axidraw/src/axidraw.ts b/packages/axidraw/src/axidraw.ts
@@ -399,7 +399,7 @@ export class AxiDraw implements IReset {
 	}
 
 	/**
-	 * Syntax sugar for {@link AxiDraw.moveTo}([0, 0]).
+	 * Syntax sugar for {@link AxiDraw.moveTo} position `[0,0]`.
 	 */
 	home() {
 		return this.moveTo(ZERO2);

diff --git a/packages/binary/src/float.ts b/packages/binary/src/float.ts
@@ -21,8 +21,8 @@ export const intBitsToFloat: FnN = (x) => ((I32[0] = x), F32[0]);
 export const uintBitsToFloat: FnN = (x) => ((U32[0] = x), F32[0]);
 
 /**
- * Returns i32 representation of f64 as [hi, lo] tuple (takes
- * environment's Little Endianess into account).
+ * Returns i32 representation of f64 as `[hi, lo]` tuple (takes environment's
+ * Little Endianess into account).
  *
  * @param x -
  */
@@ -31,8 +31,8 @@ export const floatToIntBits64 = (x: number): [number, number] => (
 );
 
 /**
- * Returns u32 representation of f64 as [hi, lo] tuple (takes
- * environment's Little Endianess into account).
+ * Returns u32 representation of f64 as `[hi, lo]` tuple (takes environment's
+ * Little Endianess into account).
  *
  * @param x -
  */
@@ -85,28 +85,28 @@ const __f2u: FnN3 = (x, n, p) =>
 	x < 0 ? (x < -1 ? n : x * n) : x > 1 ? p : x * p;
 
 /**
- * Converts normalized float ([-1..1] range) to u8.
+ * Converts normalized float (`[-1,1]` range) to u8.
  *
  * @param x -
  */
 export const f32u8: FnN = (x) => __f2u(x, 0x80, 0x7f) & 0xff;
 
 /**
- * Converts normalized float ([-1..1] range) to u16.
+ * Converts normalized float (`[-1,1]` range) to u16.
  *
  * @param x -
  */
 export const f32u16: FnN = (x) => __f2u(x, 0x8000, 0x7fff) & 0xffff;
 
 /**
- * Converts normalized float ([-1..1] range) to u24.
+ * Converts normalized float (`[-1,1]` range) to u24.
  *
  * @param x -
  */
 export const f32u24: FnN = (x) => __f2u(x, 0x80_0000, 0x7f_ffff) & 0xff_ffff;
 
 /**
- * Converts normalized float ([-1..1] range) to u32.
+ * Converts normalized float (`[-1,1]` range) to u32.
  *
  * @param x -
  */

diff --git a/packages/binary/src/int.ts b/packages/binary/src/int.ts
@@ -3,7 +3,7 @@ import type { FnN } from "@thi.ng/api";
 
 /**
  * Converts signed i8 to unsigned u8 value. Input is assumed to be in
- * [-0x80,0x7f] range. Does NOT perform clamping. Branchless.
+ * `[-0x80,0x7f]` range. Does NOT perform clamping. Branchless.
  *
  * @param x
  * @returns
@@ -12,7 +12,7 @@ export const i8u8: FnN = (x) => (x >>> 0) & 0xff;
 
 /**
  * Converts signed i16 to unsigned u16 value. Input is assumed to be in
- * [-0x8000,0x7fff] range. Does NOT perform clamping. Branchless.
+ * `[-0x8000,0x7fff]` range. Does NOT perform clamping. Branchless.
  *
  * @param x
  * @returns

diff --git a/packages/binary/src/swizzle.ts b/packages/binary/src/swizzle.ts
@@ -3,8 +3,8 @@ import type { FnN, FnN3 } from "@thi.ng/api";
 import type { Lane16, Lane2, Lane4, Lane8 } from "./api.js";
 
 /**
- * Extracts 16-bit lane from given 32bit uint and returns as unsigned
- * half word [0x0000 .. 0xffff].
+ * Extracts 16-bit lane from given 32bit uint and returns as unsigned half word
+ * `[0x0000,0xffff]`.
  *
  * - Lane #0: bits 16-31
  * - Lane #1: bits 0-15
@@ -16,8 +16,8 @@ export const lane16 = (x: number, lane: Lane16) =>
 	(x >>> ((1 - lane) << 4)) & 0xffff;
 
 /**
- * Extracts 8-bit lane from given 32bit uint and returns as unsigned
- * byte [0x00 .. 0xff].
+ * Extracts 8-bit lane from given 32bit uint and returns as unsigned byte
+ * `[0x00,0xff]`.
  *
  * - Lane #0: bits 24-31
  * - Lane #1: bits 16-23
@@ -31,8 +31,8 @@ export const lane8 = (x: number, lane: Lane8) =>
 	(x >>> ((3 - lane) << 3)) & 0xff;
 
 /**
- * Extracts 4-bit lane from given 32bit uint and returns as unsigned
- * nibble [0x00 .. 0x0f].
+ * Extracts 4-bit lane from given 32bit uint and returns as unsigned nibble
+ * `[0x00,0x0f]`.
  *
  * - Lane #0: bits 28-31
  * - Lane #1: bits 24-27

diff --git a/packages/cellular/src/1d.ts b/packages/cellular/src/1d.ts
@@ -65,7 +65,7 @@ export const WOLFRAM7: Kernel = [[-3, 0], ...WOLFRAM5, [3, 0]];
  *
  * Automata rules are encoded as JS `BigInt` values and are considered
  * anisotropic by default. If isotropy is desired, it has to be explicitly
- * pre-encoded [out of scope of this library]. There's also built-in optional
+ * pre-encoded (out of scope of this library). There's also built-in optional
  * support for position independent neighborhood encoding, only considering the
  * number/count of non-zero cells. An encoded rule ID and its overall magnitude
  * is directly related and dependent on the size and shape of its kernel config,

diff --git a/packages/checks/src/is-ascii.ts b/packages/checks/src/is-ascii.ts
@@ -1,13 +1,13 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Returns true iff all chars are in ASCII range [0x00 .. 0x7f]
+ * Returns true iff all chars are in ASCII range `[0x00,0x7f]`
  *
  * @param x -
  */
 export const isASCII = (x: string) => /^[\x00-\x7f]+$/.test(x);
 
 /**
- * Returns true iff all chars are in printable ASCII range [0x20 .. 0x7e]
+ * Returns true iff all chars are in printable ASCII range `[0x20,0x7e]`
  *
  * @param x -
  */