docs: update/clean docstrings in various pkgs

Author: postspectacular

packages/associative/src/api.ts

@@ -72,7 +72,7 @@ export interface HashMapOpts<K> {
 	 */
 	equiv?: Predicate2<K>;
 	/**
-	 * Normalized max load factor in the open (0..1) interval. The map
+	 * Normalized max load factor in the open `(0,1)` interval. The map
 	 * will be resized (doubled in size) and all existing keys rehashed
 	 * every time a new key is to be added and the current size exceeds
 	 * this normalized load.

packages/axidraw/src/api.ts

@@ -13,7 +13,7 @@ export type StopCommand = ["stop"];
 /** Return plotter to initial XY position */
 export type HomeCommand = ["home"];
 
-/** Reset curr position as home (0,0) */
+/** Reset curr position as home `(0,0)` */
 export type ResetCommand = ["reset"];
 
 /** Turn XY motors on/off */
@@ -115,7 +115,7 @@ export interface AxiDrawOpts {
 	 * thi.ng/units `quantity()`), the units used to define these dimensions are
 	 * irrelevant (and independent of {@link AxiDrawOpts.unitsPerInch}!) and
 	 * will be automatically converted. Also, the resulting bounds will always
-	 * be based on [0, 0].
+	 * be based on `[0,0]`.
 	 *
 	 * List of paper sizes/presets:
 	 * https://github.com/thi-ng/umbrella/blob/develop/packages/units/README.md#constants
@@ -205,7 +205,7 @@ export interface AxiDrawOpts {
 	 * means the available horizontal drawing space will be reduced by the same
 	 * amount...
 	 *
-	 * @defaultValue [0, 0]
+	 * @defaultValue `[0,0]`
 	 */
 	home: ReadonlyVec;
 	/**

packages/binary/src/edit.ts

@@ -7,7 +7,7 @@ import { defMask } from "./mask.js";
  * Clears bit in given uint `x`.
  *
  * @param x - value
- * @param bit - bit number (0..31)
+ * @param bit - bit number `(0,31)`
  */
 export const bitClear = (x: number, bit: Bit) => (x & ~(1 << bit)) >>> 0;
 
@@ -23,7 +23,7 @@ export const bitFlip = (x: number, bit: Bit) => (x ^ (1 << bit)) >>> 0;
  * Sets bit in given uint `x`.
  *
  * @param x - value
- * @param bit - bit number (0..31)
+ * @param bit - bit number `(0,31)`
  */
 export const bitSet = (x: number, bit: Bit) => (x | (1 << bit)) >>> 0;
 

packages/bitfield/src/bitfield.ts

@@ -171,7 +171,7 @@ export class BitField implements IClear, ICopy<BitField>, ILength {
 
 	/**
 	 * Computes the Jaccard similarity with given `field`. Returns a value in
-	 * [0..1] interval: 1.0 if `a` and `b` are equal, or 0.0 if none of the
+	 * `[0,1]` interval: 1.0 if `a` and `b` are equal, or 0.0 if none of the
 	 * components match.
 	 *
 	 * @remarks

packages/blurhash/src/encode.ts

@@ -14,8 +14,8 @@ const BASE83 = new BaseNEncoder(B83_CHARS);
 
 /**
  * Computes the blurhash for the given ABGR 32bit pixel array, image size and
- * detail settings (`detailX` & `detailY` both in [1..9] range, X default = 4, Y
- * default is same as X value).
+ * detail settings (`detailX` & `detailY` both in `[1,9]` range, X default = 4,
+ * Y default is same as X value).
  *
  * @param pixels
  * @param width

packages/cellular/src/1d.ts

@@ -76,7 +76,7 @@ export const WOLFRAM7: Kernel = [[-3, 0], ...WOLFRAM5, [3, 0]];
  * ```
  *
  * This example kernel defines a 5-cell neighborhood with a max. short term
- * memory of one additional previous generation (i.e. the [-2,1] and [2,1]
+ * memory of one additional previous generation (i.e. the `[-2,1]` and `[2,1]`
  * offsets)
  *
  * The rules related to this kernel have a 32 bit address space (4 billion

packages/color/src/api.ts

@@ -79,7 +79,7 @@ export interface ChannelSpec {
 	 * color spaces to be slightly outside that sRGB gamut. These are soft
 	 * limits, for orientation only.
 	 *
-	 * @defaultValue [0,1]
+	 * @defaultValue `[0,1]`
 	 */
 	range?: Range;
 	/**
@@ -226,7 +226,7 @@ export interface TypedColor<T>
 
 	/**
 	 * Randomizes all color channels based on channel ranges defined for this
-	 * color type (usually [0..1] interval). Alpha channel will remain
+	 * color type (usually `[0,1]` interval). Alpha channel will remain
 	 * untouched.
 	 *
 	 * @param rnd -

packages/color/src/clamp.ts

@@ -6,8 +6,8 @@ import type { Color, ReadonlyColor } from "./api.js";
 import { __ensureAlpha } from "./internal/ensure.js";
 
 /**
- * Clamps all color channels to [0,1] interval and calls `ensureAlpha` to ensure
- * alpha channel is defined (if missing sets it to `alpha`, default: 1).
+ * Clamps all color channels to `[0,1]` interval and calls `ensureAlpha` to
+ * ensure alpha channel is defined (if missing sets it to `alpha`, default: 1).
  *
  * @remarks
  * If `out` is null, the resulting color will be written back into `src`.
@@ -31,8 +31,8 @@ export const clamp = (out: Color | null, src: ReadonlyColor, alpha = 1) =>
 	);
 
 /**
- * Similar to {@link clamp}, but calls `ensureHue` to fold (instead of
- * clamping) the hue into [0,1] interval.
+ * Similar to {@link clamp}, but calls `ensureHue` to fold (instead of clamping)
+ * the hue into the `[0,1]` interval.
  *
  * @remarks
  * If `out` is null, the resulting color will be written back into `src`.

packages/color/src/cosine-gradients.ts

@@ -167,7 +167,7 @@ export const COSINE_GRADIENTS: Record<CosineGradientPreset, CosGradientSpec> = {
 
 /**
  * Computes a single linear RGBA color for given gradient spec and normalized
- * position `t` (in [0..1] interval).
+ * position `t` (in `[0,1]` interval).
  *
  * @param spec -
  * @param t -

packages/color/src/hcy/hcy.ts

@@ -37,7 +37,7 @@ export declare class HCY implements TypedColor<HCY> {
 /**
  * @remarks
  * Note: As with other hue-based color modes in this package, the hue is stored
- * normalized (in [0..1] interval) and NOT as degrees.
+ * normalized (in `[0,1]` interval) and NOT as degrees.
  */
 export const hcy = <ColorFactory<HCY>>defColor({
 	mode: "hcy",

packages/color/src/hsi/hsi.ts

@@ -37,7 +37,7 @@ export declare class HSI implements TypedColor<HSI> {
 /**
  * @remarks
  * Note: As with other hue-based color modes in this package, the hue is stored
- * normalized (in [0..1] interval) and NOT as degrees.
+ * normalized (in `[0,1]` interval) and NOT as degrees.
  */
 export const hsi = <ColorFactory<HSI>>defColor({
 	mode: "hsi",

packages/color/src/hsl/hsl.ts

@@ -38,7 +38,7 @@ export declare class HSL implements TypedColor<HSL> {
 /**
  * @remarks
  * Note: As with other hue-based color modes in this package, the hue is stored
- * normalized (in [0..1] interval) and NOT as degrees.
+ * normalized (in `[0,1]` interval) and NOT as degrees.
  */
 export const hsl = <ColorFactory<HSL>>defColor({
 	mode: "hsl",

packages/color/src/hsv/hsv.ts

@@ -38,7 +38,7 @@ export declare class HSV implements TypedColor<HSV> {
 /**
  * @remarks
  * Note: As with other hue-based color modes in this package, the hue is stored
- * normalized (in [0..1] interval) and NOT as degrees.
+ * normalized (in `[0,1]` interval) and NOT as degrees.
  */
 export const hsv = <ColorFactory<HSV>>defColor({
 	mode: "hsv",

packages/color/src/lab/lab-css.ts

@@ -4,9 +4,12 @@ import { __labCss } from "../internal/css.js";
 
 /**
  * @remarks
- * Only supported in CSS Color Level 4 onwards
- * https://www.w3.org/TR/css-color-4/#specifying-lab-lch
- * https://test.csswg.org/harness/results/css-color-4_dev/grouped/ (test reports)
+ * Only supported in CSS Color Level 4 onwards.
+ *
+ * References:
+ *
+ * - https://www.w3.org/TR/css-color-4/#specifying-lab-lch
+ * - https://test.csswg.org/harness/results/css-color-4_dev/grouped/ (test reports)
  *
  * @param src -
  */

packages/color/src/lch/lch-css.ts

@@ -4,9 +4,12 @@ import { __lchCss } from "../internal/css.js";
 
 /**
  * @remarks
- * Only supported in CSS Color Level 4 onwards
- * https://www.w3.org/TR/css-color-4/#specifying-lab-lch
- * https://test.csswg.org/harness/results/css-color-4_dev/grouped/ (test reports)
+ * Only supported in CSS Color Level 4 onwards.
+ *
+ * References:
+ *
+ * - https://www.w3.org/TR/css-color-4/#specifying-lab-lch
+ * - https://test.csswg.org/harness/results/css-color-4_dev/grouped/ (test reports)
  *
  * @param src -
  */

packages/color/src/lch/lch.ts

@@ -41,7 +41,7 @@ export declare class LCH implements TypedColor<LCH> {
  *
  * @remarks
  * Note: As with other hue-based color modes in this package, the hue is stored
- * normalized (in [0..1] interval) and NOT as degrees.
+ * normalized (in `[0,1]` interval) and NOT as degrees.
  */
 export const lch = <ColorFactory<LCH>>defColor({
 	mode: "lch",

packages/color/src/mix.ts

@@ -31,8 +31,8 @@ export const defMix: FnU4<FnN3, ColorMixFn> =
  * Single channel interpolation for (normalized) hues. Always interpolates via
  * smallest angle difference, i.e. such that the effective `abs(a-b) <= 0.5`.
  *
- * @param a - start hue in [0,1) interval
- * @param b - end hue in [0,1) interval
+ * @param a - start hue in `[0,1)` interval
+ * @param b - end hue in `[0,1)` interval
  * @param t - interpolation factor
  */
 export const mixH: FnN3 = (a, b, t) => {
@@ -64,7 +64,7 @@ export const mixHNNN = defMix(mixH, mixN, mixN, mixN);
 export const mixNNHN = defMix(mixN, mixN, mixH, mixN);
 
 /**
- * Channelwise linear interpolation between colors `a` and `b` using `t` [0..1]
+ * Channelwise linear interpolation between colors `a` and `b` using `t` `[0,1]`
  * as blend factor.
  *
  * @param out -
@@ -76,7 +76,7 @@ export const mixNNNN: ColorMixFn = mixN4;
 
 /**
  * Channelwise and {@link ColorMode}-aware interpolation between colors `a` and
- * `b` using `t` [0..1] as blend factor. `a` and `b` MUST be of same color
+ * `b` using `t` `[0,1]` as blend factor. `a` and `b` MUST be of same color
  * type.
  *
  * @remarks

packages/color/src/oklab/oklab-css.ts

@@ -4,9 +4,12 @@ import { __labCss } from "../internal/css.js";
 
 /**
  * @remarks
- * Only supported in CSS Color Level 4 onwards
- * https://www.w3.org/TR/css-color-4/#specifying-lab-lch
- * https://test.csswg.org/harness/results/css-color-4_dev/grouped/ (test reports)
+ * Only supported in CSS Color Level 4 onwards.
+ *
+ * References:
+ *
+ * - https://www.w3.org/TR/css-color-4/#specifying-lab-lch
+ * - https://test.csswg.org/harness/results/css-color-4_dev/grouped/ (test reports)
  *
  * @param src -
  */

packages/color/src/oklch/oklch.ts

@@ -38,7 +38,7 @@ export declare class Oklch implements TypedColor<Oklch> {
  *
  * @remarks
  * Note: As with other hue-based color modes in this package, the hue is stored
- * normalized (in [0..1] interval) and NOT as degrees.
+ * normalized (in `[0,1]` interval) and NOT as degrees.
  *
  * Reference: https://bottosson.github.io/posts/oklab/
  */

packages/color/src/rotate.ts

@@ -14,7 +14,7 @@ import { __ensureAlpha } from "./internal/ensure.js";
  * If `out` is null, the resulting will be written back into `src`.
  *
  * As with all hue-based color modes in this package, the hue is stored
- * normalized (in [0..1] interval) and NOT as degrees. The same goes for the
+ * normalized (in `[0,1]` interval) and NOT as degrees. The same goes for the
  * rotation angle `theta`.
  *
  * Only supported for hue based color modes:

packages/color/src/transform.ts

@@ -25,7 +25,7 @@ const S8 = 0.283;
  * @param out - result
  * @param mat - transform matrix
  * @param src - source color
- * @param clampOut - true, if result should be clamped to [0..1]
+ * @param clampOut - true, if result should be clamped to `[0,1]`
  */
 export const transform = __mulV45;
 
@@ -126,7 +126,7 @@ export const hueRotateMat = (theta: number): ColorMatrix => {
 
 /**
  * Color temperature adjustment matrix. `x` controls blue/yellow, `y` controls
- * green/magenta axis (both params in [-1,1] range).
+ * green/magenta axis (both params in `[-1,1]` range).
  *
  * @param x
  * @param y

packages/color/src/xyy/xyy-xyz.ts

@@ -6,8 +6,8 @@ import { __ensureAlpha } from "../internal/ensure.js";
 
 /**
  * @remarks
- * https://en.wikipedia.org/wiki/CIE_1931_color_space#CIE_xy_chromaticity_diagram_and_the_CIE_xyY_color_space
- * https://gamedev.stackexchange.com/a/70049
+ * - https://en.wikipedia.org/wiki/CIE_1931_color_space#CIE_xy_chromaticity_diagram_and_the_CIE_xyY_color_space
+ * - https://gamedev.stackexchange.com/a/70049
  *
  * @param out -
  * @param src -

packages/color/src/xyz/xyz-xyy.ts

@@ -6,8 +6,8 @@ import { __ensureAlpha } from "../internal/ensure.js";
 
 /**
  * @remarks
- * https://en.wikipedia.org/wiki/CIE_1931_color_space#CIE_xy_chromaticity_diagram_and_the_CIE_xyY_color_space
- * https://gamedev.stackexchange.com/a/70049
+ * - https://en.wikipedia.org/wiki/CIE_1931_color_space#CIE_xy_chromaticity_diagram_and_the_CIE_xyY_color_space
+ * - https://gamedev.stackexchange.com/a/70049
  *
  * @param out -
  * @param src -

packages/colored-noise/src/pink.ts

@@ -7,7 +7,7 @@ import { preseed, sum } from "./utils.js";
  * Exponential decay (1/f) noise, based on Voss-McCarthy algorithm.
  *
  * @remarks
- * The number of internal states should be in the [4..32] range (default: 8).
+ * The number of internal states should be in the `[4,32]` range (default: 8).
  * Due to JS integer limitations, `n` > 32 are meaningless.
  *
  * References:

packages/complex/src/index.ts

@@ -22,12 +22,12 @@ export type ComplexOp1 = Fn<Complex, Complex>;
 export type ComplexOp2 = Fn2<Complex, Complex | number, Complex>;
 
 /**
- * Complex `i` aka [0, 1]
+ * Complex `i` aka `[0,1]`
  */
 export const I: Complex = Object.freeze([0, 1]);
 
 /**
- * Same as 1/i, i.e. [0, -1]
+ * Same as 1/i, i.e. `[0,-1]`
  */
 export const J: Complex = Object.freeze([0, -1]);
 

packages/date/src/timecode.ts

@@ -3,8 +3,8 @@ import { Z2 } from "@thi.ng/strings/pad-left";
 import { decomposeDuration } from "./duration.js";
 
 /**
- * Returns a time formatter for given FPS (frames / second, in [1..1000] range),
- * e.g. `HH:mm:ss:ff`. The returned function takes a single arg (time in
+ * Returns a time formatter for given FPS (frames / second, in `[1,1000]`
+ * range), e.g. `HH:mm:ss:ff`. The returned function takes a single arg (time in
  * milliseconds) and returns formatted string.
  *
  * @remarks

packages/distance/src/manhattan.ts

@@ -14,12 +14,12 @@ import type { IDistance, Metric } from "./api.js";
  * The conversion are always based on n-D squares, i.e. the assumption that the
  * distance is equally shared in each dimension.
  *
- * E.g. a Manhattan distance of 30 could be obtained from [0,0] -> [10,20], but
- * would be interpreted here as distance from [0,0] -> [15,15], which produces
- * the same Manhattan value, but yields a different Eucledian result. For lack
- * of any other information about the distance values, this is however the only
- * way to approach conversion and is sufficient for the purposes of this
- * package...
+ * E.g. a Manhattan distance of 30 could be obtained from `[0,0]` -> `[10,20]`,
+ * but would be interpreted here as distance from `[0,0]` -> `[15,15]`, which
+ * produces the same Manhattan value, but yields a different Eucledian result.
+ * For lack of any other information about the distance values, this is however
+ * the only way to approach conversion and is sufficient for the purposes of
+ * this package...
  *
  * @example
  * ```ts tangle:../export/manhattan.ts

packages/dsp/src/adsr.ts

@@ -25,7 +25,7 @@ export interface ADSROpts {
 	 */
 	d: number;
 	/**
-	 * Sustain level/gain (in [0..1] range). Default: 1
+	 * Sustain level/gain (in `[0,1]` range). Default: 1
 	 */
 	s: number;
 	/**

packages/dsp/src/foldback.ts

@@ -7,8 +7,7 @@ import { AProc } from "./aproc.js";
  * amplifies it with `amp` (default: 1/thresh).
  *
  * @remarks
- * Reference:
- * https://www.desmos.com/calculator/lkyf2ag3ta
+ * [Interactive graph](https://www.desmos.com/calculator/lkyf2ag3ta)
  *
  * @param thresh - fold threshold
  * @param amp - post amplifier