Update docstring formatting

Author: camdecoster

src/lib/clean_number.ts

@@ -10,7 +10,7 @@ const JUNK = /^['"%,$#\s']+|[, ]|['"%,$#\s']+$/g;
  * 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
+ * @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

@@ -4,8 +4,8 @@
  * 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
+ * @param v - Dividend
+ * @param d - Divisor (the modulus); assumed positive
  */
 export function mod(v: number, d: number) {
     const out = v % d;
@@ -16,8 +16,8 @@ export function mod(v: number, d: number) {
  * 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
+ * @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

@@ -3,16 +3,16 @@
 const NUMBER_REGEX = '([2-9]|[1-9][0-9]+)?';
 
 /**
- * make a regex for matching counter ids/names ie xaxis, xaxis2, xaxis10...
+ * Make a regex for matching counter ids/names, for example xaxis, xaxis2, xaxis10
  *
- * @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
- *      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 head - The head of the pattern, for example 'x' matches 'x', 'x2', 'x10'.
+ *      'xy' is a special case for cartesian subplots: it matches 'x2y3'.
+ * @param tail - A fixed piece after the id.
+ *      For example, counterRegex('scene', '.annotations') for scene2.annotations.
+ * @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) {
+export function counter(head: string, tail: string = '', openEnded?: boolean, matchBeginning?: boolean) {
     const fullTail = tail + (openEnded ? '' : '$');
     const startWithPrefix = matchBeginning === false ? '' : '^';
     return head === 'xy'

src/lib/sort_object_keys.ts

@@ -3,7 +3,7 @@
 /**
  * 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
+ * @param obj - Object whose own enumerable keys will be listed and sorted
  */
 function sortObjectKeys(obj: Record<string, any>) {
     return Object.keys(obj).sort();

src/plots/map/get_map_fit_bounds.ts

@@ -24,7 +24,7 @@ interface FitBoundsTrace extends Pick<ScattermapData, 'subplot' | 'visible'> {
  *     that isn't implemented here.
  *
  * @param fullData - The full data array (post supply-defaults)
- * @param subplotId - e.g. `'map'`, `'map2'`
+ * @param subplotId - Subplot id, for example `'map'` or `'map2'`
  */
 export function getMapFitBounds(fullData: FitBoundsTrace[], subplotId: string): LonLatBox | null {
     const coordinates: [number, number][] = [];

src/types/core/api.d.ts

@@ -183,11 +183,11 @@ export interface ValidateTemplateResult {
 /**
  * Create a new plot at `root`. Replaces any existing plot.
  *
- * @param root - graph div id or element
- * @param data - trace data array
- * @param layout - layout overrides
- * @param config - config overrides
- * @returns the graph div once the plot has rendered
+ * @param root - Graph div id or element
+ * @param data - Trace data array
+ * @param layout - Layout overrides
+ * @param config - Config overrides
+ * @returns The graph div once the plot has rendered
  */
 export function newPlot(
     root: Root,
@@ -199,9 +199,9 @@ export function newPlot(
  * Create a new plot at `root` from a figure-shaped object containing
  * `data`/`layout`/`config`/`frames`. Replaces any existing plot.
  *
- * @param root - graph div id or element
- * @param figure - figure-shaped object
- * @returns the graph div once the plot has rendered
+ * @param root - Graph div id or element
+ * @param figure - Figure-shaped object
+ * @returns The graph div once the plot has rendered
  */
 export function newPlot(
     root: Root,
@@ -217,17 +217,17 @@ export function purge(root: Root): void;
 /**
  * Update trace properties (style) on the existing plot.
  *
- * @param aobj - update object whose keys are attribute paths
- * @param traces - trace index/indices to update (defaults to all)
+ * @param aobj - Update object whose keys are attribute paths
+ * @param traces - Trace index/indices to update (defaults to all)
  */
 export function restyle(root: Root, aobj: Data, traces?: number[] | number): Promise<PlotlyHTMLElement>;
 
 /**
  * Update both trace and layout properties in a single call.
  *
- * @param traceUpdate - per-trace updates
- * @param layoutUpdate - layout updates
- * @param traces - trace index/indices `traceUpdate` applies to
+ * @param traceUpdate - Per-trace updates
+ * @param layoutUpdate - Layout updates
+ * @param traces - Trace index/indices `traceUpdate` applies to
  */
 export function update(
     root: Root,
@@ -239,8 +239,8 @@ export function update(
 /**
  * Add one or more traces to an existing plot.
  *
- * @param traces - trace(s) to add
- * @param newIndices - position(s) in `data` where the traces should land
+ * @param traces - Trace(s) to add
+ * @param newIndices - Position(s) in `data` where the traces should land
  */
 export function addTraces(
     root: Root,
@@ -254,8 +254,8 @@ export function deleteTraces(root: Root, indices: number[] | number): Promise<Pl
 /**
  * Reorder existing traces.
  *
- * @param currentIndices - current trace indices to move
- * @param newIndices - destination indices; if omitted, traces move to the end
+ * @param currentIndices - Current trace indices to move
+ * @param newIndices - Destination indices; if omitted, traces move to the end
  */
 export function moveTraces(
     root: Root,
@@ -307,8 +307,8 @@ export function register(modules: PlotlyModule | PlotlyModule[]): void;
 /**
  * Animate to a frame, frame group, or sequence of frames.
  *
- * @param frameOrGroupNameOrFrameList - frame name, group name, or list of either
- * @param opts - animation options (frame timing, transition, mode, …)
+ * @param frameOrGroupNameOrFrameList - Frame name, group name, or list of either
+ * @param opts - Animation options (frame timing, transition, mode, …)
  */
 export function animate(
     root: Root,