docs: add @param descriptions (pkgs A-C)

thi-ng · Nov 17, 2019 · 354817f · 354817f
1 parent baecbad
commit 354817f
Show file tree

Hide file tree

Showing 70 changed files with 307 additions and 277 deletions.
diff --git a/packages/adjacency/src/binary.ts b/packages/adjacency/src/binary.ts
@@ -8,11 +8,12 @@ export class AdjacencyBitMatrix implements IGraph {
      * Creates adjacency matrix with capacity `n` (max vertices) from
      * given edge pairs. Each edge is `[dest-node src-node]`.
      *
+     * @remarks
      * If `undirected` is true, creates symmetrical adjacencies.
      *
-     * @param n -
-     * @param edges -
-     * @param undirected -
+     * @param n - max vertices
+     * @param edges - edge pairs
+     * @param undirected -true, if undirected
      */
     static fromEdges(
         n: number,
@@ -58,7 +59,7 @@ export class AdjacencyBitMatrix implements IGraph {
     /**
      * Resizes matrix to new size given.
      *
-     * @param n -
+     * @param n - new max vertices
      */
     resize(n: number) {
         this.mat.resize(n);

diff --git a/packages/adjacency/src/disjoint-set.ts b/packages/adjacency/src/disjoint-set.ts
@@ -14,7 +14,7 @@ export class DisjointSet {
     /**
      * Creates new instance with `n` initial singular subsets.
      *
-     * @param n -
+     * @param n - initial capacity, ID range [0..n)
      */
     constructor(n: number) {
         const roots = (this.roots = new Uint32Array(n));
@@ -30,7 +30,7 @@ export class DisjointSet {
      * already is unified with some other ID, this will always return
      * `id` itself (since each node is initially its own root).
      *
-     * @param id -
+     * @param id - node ID
      */
     canonical(id: number) {
         const roots = this.roots;
@@ -44,8 +44,8 @@ export class DisjointSet {
      * Connects combines the trees of the given two node IDs and returns
      * the new resulting canonical tree root ID.
      *
-     * @param a -
-     * @param b -
+     * @param a - node ID
+     * @param b - node ID
      */
     union(a: number, b: number) {
         const rootA = this.canonical(a);
@@ -68,8 +68,8 @@ export class DisjointSet {
      * Returns true, if the given two nodes belong to the same tree /
      * subset.
      *
-     * @param a -
-     * @param b -
+     * @param a - node ID
+     * @param b - node ID
      */
     unified(a: number, b: number) {
         return this.canonical(a) === this.canonical(b);
@@ -78,6 +78,8 @@ export class DisjointSet {
     /**
      * Returns a `Map` of all subsets (connected components) with their
      * canonical tree root IDs as keys and arrays of node IDs as values.
+     *
+     * @remarks
      * If only the number of subsets is required, use the `count`
      * property of this class instance instead (O(1), updated with each
      * call to {@link DisjointSet.union}).

diff --git a/packages/adjacency/src/mst.ts b/packages/adjacency/src/mst.ts
@@ -40,10 +40,10 @@ import { DisjointSet } from "./disjoint-set";
  * // [ [ 0, 1 ], [ 1, 2 ], [ 2, 3 ], [ 2, 4 ] ]
  * ```
  *
- * @param edges -
- * @param maxID -
- * @param cost -
- * @param verts -
+ * @param edges - edge pairs
+ * @param maxID - max vertex ID (+1)
+ * @param cost - cost function
+ * @param verts - vertices / graph nodes
  */
 export const mst = <T>(
     edges: T[],

diff --git a/packages/adjacency/src/sparse.ts b/packages/adjacency/src/sparse.ts
@@ -12,12 +12,13 @@ export class AdjacencyMatrix extends CSR implements IGraph {
      * Creates adjacency matrix from given edge pairs. Each edge is
      * `[dest-node src-node]`.
      *
+     * @remarks
      * If `undirected` is true (default: false), creates symmetrical
      * edges.
      *
      * @param n - max number of vertices
-     * @param edges -
-     * @param undirected -
+     * @param edges - edge pairs
+     * @param undirected - true, if undirected
      */
     static fromEdges(
         n: number,
@@ -94,7 +95,7 @@ export class AdjacencyMatrix extends CSR implements IGraph {
 
     /**
      *
-     * @param deg -
+     * @param deg - degree type
      */
     degreeMat(deg: DegreeType = DegreeType.OUT) {
         const res = CSR.empty(this.m);
@@ -154,10 +155,15 @@ export class AdjacencyMatrix extends CSR implements IGraph {
     }
 
     /**
-     * Computes: `I - nA + n^2 * (D - I)`
+     * Computes: `I - nA + n^2 * (D - I)`, where `I` is the unit matrix,
+     * `A` the adjacency matrix, `D` the degree matrix, and `n` is a
+     * (complex-valued) number.
+     *
+     * @remarks
+     * See {@link AdjacencyMatrix.degreeMat}.
      *
-     * @param n -
-     * @param deg -
+     * @param n - scale factor
+     * @param deg - degree matrix
      */
     deformedLaplacian(n: number, deg?: CSR) {
         deg = deg || this.degreeMat();

diff --git a/packages/api/src/api/compare.ts b/packages/api/src/api/compare.ts
@@ -1,8 +1,10 @@
 import { Fn2 } from "./fn";
 
 /**
- * Generic 2-element comparator function type alias. Must follow this
- * contract and return:
+ * Generic 2-element comparator function type alias.
+ *
+ * @remarks
+ * Must follow this contract and return:
  *
  * - negative if `a < b`
  * - zero if `a == b`
@@ -16,12 +18,15 @@ export type Comparator<T> = Fn2<T, T, number>;
 export interface ICompare<T> {
     /**
      * Compares this value with given value `x`. MUST follow same
-     * contract as `Comparator`. MUST return 0 if the type also
-     * implements `IEquiv` and `equiv` returns true for same `x`.
+     * contract as {@link Comparator}.
+     *
+     * @remarks
+     * MUST return 0 if the type also implements `IEquiv` and `equiv`
+     * returns true for same `x`.
      *
-     * Also see `IHash`.
+     * Also see {@link IHash}.
      *
-     * @param x -
+     * @param x - compare value
      */
     compare(x: T): number;
 }
diff --git a/packages/api/src/api/contains.ts b/packages/api/src/api/contains.ts
@@ -6,7 +6,7 @@ export interface IContains<T> {
     /**
      * Returns `true` if `x` is part of collection.
      *
-     * @param x -
+     * @param x - value to check for
      */
     contains(x: T): boolean;
 }
diff --git a/packages/api/src/api/equiv.ts b/packages/api/src/api/equiv.ts
@@ -1,9 +1,9 @@
 export interface IEquiv {
     /**
      * Returns `true` if this *value* is equivalent to `o`. Also see
-     * `ICompare.compare` and `IHash.hash`.
+     * {@link ICompare.compare} and {@link IHash.hash}.
      *
-     * @param o -
+     * @param o - value to check for equivalence
      */
     equiv(o: any): boolean;
 }

diff --git a/packages/api/src/api/meta.ts b/packages/api/src/api/meta.ts
@@ -8,7 +8,7 @@ export interface IMeta<T> {
      * Returns a copy of the original value with given metadata
      * attached.
      *
-     * @param meta -
+     * @param meta - meta data
      */
     withMeta(meta: any): T;
 }
diff --git a/packages/api/src/api/set.ts b/packages/api/src/api/set.ts
@@ -10,13 +10,13 @@ export interface ISet<V, T> extends IInto<V, T> {
     /**
      * Conjoins/adds value `x` to set.
      *
-     * @param x -
+     * @param x - value to add
      */
     conj(x: V): T;
     /**
      * Disjoins/removes value `x` from set.
      *
-     * @param x -
+     * @param x - value to remove
      */
     disj(x: V): T;
 }
diff --git a/packages/api/src/api/typedarray.ts b/packages/api/src/api/typedarray.ts
@@ -158,7 +158,7 @@ export interface TypedArrayTypeMap extends Record<Type | GLType, TypedArray> {
  * Constructs new typed array of given {@link Type}/{@link GLType}. Supports all
  * arities of standard typed array ctors.
  *
- * @param type -
+ * @param type - array type enum
  */
 // prettier-ignore
 export function typedArray<T extends Type | GLType>(type: T, length: number): TypedArrayTypeMap[T];
@@ -174,7 +174,7 @@ export function typedArray<T extends Type | GLType>(type: T, ...xs: any[]) {
  * Returns the smallest possible *unsigned* int type enum for given `x`.
  * E.g. if `x <= 256`, the function returns `Type.U8`.
  *
- * @param x -
+ * @param x - value to classify
  */
 export const uintType = (x: number): UintType =>
     x <= 0x100 ? Type.U8 : x <= 0x10000 ? Type.U16 : Type.U32;
@@ -183,7 +183,7 @@ export const uintType = (x: number): UintType =>
  * Returns the smallest possible *signed* int type enum for given `x`.
  * E.g. if `x >= -128 && x < 128`, the function returns `Type.I8`.
  *
- * @param x -
+ * @param x - value to classify
  */
 export const intType = (x: number): IntType =>
     x >= -0x80 && x < 0x80

diff --git a/packages/api/src/decorators/configurable.ts b/packages/api/src/decorators/configurable.ts
@@ -2,7 +2,7 @@
  * Property decorator factory. Sets `configurable` flag of PropertyDescriptor
  * to given state.
  *
- * @param state -
+ * @param state - true, if propoerty is configurable
  */
 export const configurable = (state: boolean): MethodDecorator =>
     function(_: any, __: string | symbol, descriptor: PropertyDescriptor) {

diff --git a/packages/api/src/decorators/sealed.ts b/packages/api/src/decorators/sealed.ts
@@ -1,7 +1,7 @@
 /**
  * Class decorator. Seals both constructor and prototype.
  *
- * @param constructor -
+ * @param constructor - class ctor to seal
  */
 export const sealed = (constructor: Function) => {
     Object.seal(constructor);

diff --git a/packages/arrays/src/binary-search.ts b/packages/arrays/src/binary-search.ts
@@ -24,10 +24,10 @@ import { compare, compareNumAsc } from "@thi.ng/compare";
  * // -3
  * ```
  *
- * @param buf -
- * @param x -
- * @param key -
- * @param cmp -
+ * @param buf - array
+ * @param x - search value
+ * @param key - key function
+ * @param cmp - comparator
  */
 export const binarySearch = <A, B>(
     buf: ArrayLike<A>,
@@ -57,9 +57,9 @@ export const binarySearch = <A, B>(
  * supporting custom comparators (default:
  * {@link @thi.ng/compare#compareNumAsc}).
  *
- * @param buf -
- * @param x -
- * @param cmp -
+ * @param buf - array
+ * @param x - search value
+ * @param cmp - comparator
  */
 export const binarySearchNumeric = (
     buf: ArrayLike<number>,

diff --git a/packages/arrays/src/ends-with.ts b/packages/arrays/src/ends-with.ts
@@ -12,9 +12,9 @@ import { equiv as _eq } from "@thi.ng/equiv";
  *
  * {@link startsWith}
  *
- * @param buf -
- * @param needle -
- * @param equiv -
+ * @param buf - array
+ * @param needle - search values (array)
+ * @param equiv - equivalence predicate
  */
 export const endsWith = <T>(
     buf: ArrayLike<T>,

diff --git a/packages/arrays/src/find.ts b/packages/arrays/src/find.ts
@@ -5,34 +5,34 @@ import { equiv as _equiv } from "@thi.ng/equiv";
  * Similar to `Array.find()`, but uses {@link @thi.ng/equiv#equiv} as
  * default predicate.
  *
- * @param src -
- * @param x -
- * @param equiv -
+ * @param buf - array
+ * @param x - search value
+ * @param equiv - equivalence predicate
  */
 export const find = <T>(
-    src: ArrayLike<T>,
+    buf: ArrayLike<T>,
     x: T,
     equiv: Predicate2<T> = _equiv
 ) => {
-    const i = findIndex(src, x, equiv);
-    return i !== -1 ? src[i] : undefined;
+    const i = findIndex(buf, x, equiv);
+    return i !== -1 ? buf[i] : undefined;
 };
 
 /**
  * Similar to `Array.findIndex()`, but uses {@link @thi.ng/equiv#equiv}
  * as default predicate.
  *
- * @param src -
- * @param x -
- * @param equiv -
+ * @param buf - array
+ * @param x - search value
+ * @param equiv - equivalence predicate
  */
 export const findIndex = <T>(
-    src: ArrayLike<T>,
+    buf: ArrayLike<T>,
     x: T,
     equiv: Predicate2<T> = _equiv
 ) => {
-    for (let i = src.length; --i >= 0; ) {
-        if (equiv(x, src[i])) return i;
+    for (let i = buf.length; --i >= 0; ) {
+        if (equiv(x, buf[i])) return i;
     }
     return -1;
 };
diff --git a/packages/arrays/src/fuzzy-match.ts b/packages/arrays/src/fuzzy-match.ts
@@ -14,9 +14,9 @@ import { equiv as _eq } from "@thi.ng/equiv";
  *
  * {@link @thi.ng/transducers#filterFuzzy}
  *
- * @param domain -
- * @param query -
- * @param equiv -
+ * @param domain - array
+ * @param query - search value
+ * @param equiv - equivalence predicate
  */
 export const fuzzyMatch = <T>(
     domain: ArrayLike<T>,

diff --git a/packages/arrays/src/is-sorted.ts b/packages/arrays/src/is-sorted.ts
@@ -20,10 +20,10 @@ import { compare } from "@thi.ng/compare";
  * // true
  * ```
  *
- * @param arr -
- * @param cmp -
- * @param start -
- * @param end -
+ * @param arr - array
+ * @param cmp - comparator
+ * @param start - start index
+ * @param end - end index
  */
 export const isSorted = <T>(
     arr: ArrayLike<T>,

diff --git a/packages/arrays/src/peek.ts b/packages/arrays/src/peek.ts
@@ -1,6 +1,6 @@
 /**
  * Returns last element of given array or `undefined` if array is empty.
  *
- * @param x -
+ * @param buf - array
  */
-export const peek = <T>(x: ArrayLike<T>) => x[x.length - 1];
+export const peek = <T>(buf: ArrayLike<T>) => buf[buf.length - 1];
diff --git a/packages/arrays/src/quicksort.ts b/packages/arrays/src/quicksort.ts
@@ -33,11 +33,11 @@ import { swap } from "./swap";
  * // [ -1, -3, -4, -5, -8 ]
  * ```
  *
- * @param arr -
- * @param _cmp -
- * @param _swap -
- * @param start -
- * @param end -
+ * @param arr - array to sort
+ * @param _cmp - comparator
+ * @param _swap - swap function
+ * @param start - start index
+ * @param end - end index (inclusive)
  */
 // prettier-ignore
 export function quickSort<T>(arr: T[], _cmp?: Comparator<T>, _swap?: Fn3<T[], number, number, void>, start?: number, end?: number): T[];