Update JSDoc descriptions

Author: camdecoster

src/lib/clean_number.ts

@@ -7,8 +7,10 @@ import { BADNUM } from '../constants/numerical';
 const JUNK = /^['"%,$#\s']+|[, ]|['"%,$#\s']+$/g;
 
 /**
- * cleanNumber: remove common leading and trailing cruft
+ * Remove common leading and trailing cruft from a value and coerce it to a number.
  * Always returns either a number or BADNUM.
+ *
+ * @param v - value to clean; strings have leading/trailing junk characters stripped before numeric coercion
  */
 function cleanNumber(v: any): number | undefined {
     if (typeof v === 'string') v = v.replace(JUNK, '');

src/lib/mod.ts

@@ -1,17 +1,23 @@
 'use strict';
 
 /**
- * sanitized modulus function that always returns in the range [0, d)
- * rather than (-d, 0] if v is negative
+ * Sanitized modulus function that always returns in the range [0, d)
+ * rather than (-d, 0] if v is negative.
+ *
+ * @param v - dividend
+ * @param d - divisor (the modulus); assumed positive
  */
 export function mod(v: number, d: number) {
     const out = v % d;
     return out < 0 ? out + d : out;
 }
 
 /**
- * sanitized modulus function that always returns in the range [-d/2, d/2]
- * rather than (-d, 0] if v is negative
+ * Sanitized modulus function that always returns in the range [-d/2, d/2]
+ * rather than (-d, 0] if v is negative.
+ *
+ * @param v - dividend
+ * @param d - divisor (the modulus); assumed positive
  */
 export function modHalf(v: number, d: number) {
     return Math.abs(v) > d / 2 ? v - Math.round(v / d) * d : v;

src/lib/regex.ts

@@ -5,12 +5,12 @@ const NUMBER_REGEX = '([2-9]|[1-9][0-9]+)?';
 /**
  * make a regex for matching counter ids/names ie xaxis, xaxis2, xaxis10...
  *
- * @param head: the head of the pattern, eg 'x' matches 'x', 'x2', 'x10' etc.
+ * @param head - the head of the pattern, eg 'x' matches 'x', 'x2', 'x10' etc.
  *      'xy' is a special case for cartesian subplots: it matches 'x2y3' etc
- * @param tail: a fixed piece after the id
+ * @param tail - a fixed piece after the id
  *      eg counterRegex('scene', '.annotations') for scene2.annotations etc.
- * @param openEnded: if true, the string may continue past the match.
- * @param matchBeginning: if false, the string may start before the match.
+ * @param openEnded - if true, the string may continue past the match.
+ * @param matchBeginning - if false, the string may start before the match.
  */
 export function counter(head: string, tail: string = '', openEnded: boolean, matchBeginning: boolean) {
     const fullTail = tail + (openEnded ? '' : '$');

src/lib/sort_object_keys.ts

@@ -1,5 +1,10 @@
 'use strict';
 
+/**
+ * Return the keys of an object in lexicographic (default `Array.prototype.sort`) order.
+ *
+ * @param obj - object whose own enumerable keys will be listed and sorted
+ */
 function sortObjectKeys(obj: Record<string, any>) {
     return Object.keys(obj).sort();
 }