docs: align JSDoc throws ordering across stats/array outliers

[Planeshifter]

Description

Aligning outliers in stats/array with namespace majority patterns (random namespace pick, seed 1777451199).

This pull request:

• Reorders @throws JSDoc tags in lib/main.js for 12 packages in the stats/array namespace so they match the order in which the corresponding runtime checks fire (isCollection array-like check before contains data-type check). 57/69 (83%) of namespace packages already follow this ordering; the 12 stdev/nanstdev family packages had them swapped.
• Pure JSDoc reordering. No code, test, example, benchmark, or type-definition changes.

Namespace summary

• Target namespace: stats/array
• Members analyzed: 69 (no autogenerated packages excluded)
• Features analyzed: file tree, package.json shape, README section sequence, manifest.json shape, test/benchmark/examples filenames, public signature, return kind, validation prologue, error construction, JSDoc shape (param/returns/throws/example), @stdlib/* dependency set
• Features with clear majority (≥75%): file tree (100%), package.json top-level keys (100%), README section sequence (100% on the Usage / Notes / Examples prefix), test/benchmark/examples filenames (100%), returnKind=value (100%), errorConstruction=format (100%), jsdocShape.hasExample=true (100%), JSDoc throws ordering "array-like before data type" (83%)
• Features without clear majority (excluded): validation-prologue exact sequence (varies legitimately by function arity / cov vs. by-callback), public-signature length (varies by function purpose), keyword arrays (vary by statistic family), References README section (22%, intentional add-on for packages citing literature)

Per-outlier package notes

stats/array/stdev

Reorder @throws tags to match runtime check order. The current JSDoc lists the unsupported-data-type error before the non-array-like error, but isCollection is checked first at runtime. Swap the two tags to restore consistency with the 83% majority of packages in this namespace.

stats/array/stdevch

Reorder @throws tags to match runtime check order. The current JSDoc lists the unsupported-data-type error before the non-array-like error, but isCollection is checked first at runtime. Swap the two tags to restore consistency with the 83% majority of packages in this namespace.

stats/array/stdevpn

Reorder @throws tags to match runtime check order. The current JSDoc lists the unsupported-data-type error before the non-array-like error, but isCollection is checked first at runtime. Swap the two tags to restore consistency with the 83% majority of packages in this namespace.

stats/array/stdevtk

Reorder @throws tags to match runtime check order. The current JSDoc lists the unsupported-data-type error before the non-array-like error, but isCollection is checked first at runtime. Swap the two tags to restore consistency with the 83% majority of packages in this namespace.

stats/array/stdevwd

Reorder @throws tags to match runtime check order. The current JSDoc lists the unsupported-data-type error before the non-array-like error, but isCollection is checked first at runtime. Swap the two tags to restore consistency with the 83% majority of packages in this namespace.

stats/array/stdevyc

Reorder @throws tags to match runtime check order. The current JSDoc lists the unsupported-data-type error before the non-array-like error, but isCollection is checked first at runtime. Swap the two tags to restore consistency with the 83% majority of packages in this namespace.

stats/array/nanstdev

Reorder @throws tags to match runtime check order. The current JSDoc lists the unsupported-data-type error before the non-array-like error, but isCollection is checked first at runtime. Swap the two tags to restore consistency with the 83% majority of packages in this namespace.

stats/array/nanstdevch

Reorder @throws tags to match runtime check order. The current JSDoc lists the unsupported-data-type error before the non-array-like error, but isCollection is checked first at runtime. Swap the two tags to restore consistency with the 83% majority of packages in this namespace.

stats/array/nanstdevpn

Reorder @throws tags to match runtime check order. The current JSDoc lists the unsupported-data-type error before the non-array-like error, but isCollection is checked first at runtime. Swap the two tags to restore consistency with the 83% majority of packages in this namespace.

stats/array/nanstdevtk

Reorder @throws tags to match runtime check order. The current JSDoc lists the unsupported-data-type error before the non-array-like error, but isCollection is checked first at runtime. Swap the two tags to restore consistency with the 83% majority of packages in this namespace.

stats/array/nanstdevwd

Reorder @throws tags to match runtime check order. The current JSDoc lists the unsupported-data-type error before the non-array-like error, but isCollection is checked first at runtime. Swap the two tags to restore consistency with the 83% majority of packages in this namespace.

stats/array/nanstdevyc

Reorder @throws tags to match runtime check order. The current JSDoc lists the unsupported-data-type error before the non-array-like error, but isCollection is checked first at runtime. Swap the two tags to restore consistency with the 83% majority of packages in this namespace.

Related Issues

This pull request has no related issues.

Questions

No.

Other

Validation

What was checked:

• Structural feature extraction across all 69 members: file tree, package.json keys/scripts/stdlib/manifest shape, README heading sequence, test/benchmark/examples filenames. Result: identical across the namespace, no structural drift.
• Semantic feature extraction of lib/main.js for every package: public signature, return kind, validation prologue, error construction, full JSDoc shape (param tags / returns tag / throws tags / hasExample), and @stdlib/* dependency set.
• Three-agent drift validation of the JSDoc throws-ordering finding: a semantic-review agent (opus) confirmed the deviation is unintentional drift and not a mathematical justification; a cross-reference agent (opus) confirmed no test/example/benchmark/README/repl.txt/index.d.ts depends on JSDoc throws ordering and no external stdlib package quotes those JSDoc strings; a structural-review agent (sonnet) confirmed the runtime check order in each outlier matches the majority and that swapping the two @throws lines is the complete and correct fix. All three returned confirmed-drift for all 12 packages.

What was deliberately excluded:

• Features without a clear ≥75% majority (e.g., validation-prologue exact sequence, signature length, keyword arrays, optional References README section).
• The 8 *-by callback variants (max-by, min-by, nanmax-by, etc.), whose lack of a data-type predicate check is a legitimate semantic difference, not drift.
• Outliers whose tests, examples, or types would have to change to apply the correction. None were in scope here; the fix is JSDoc-only.

Checklist

• Read, understood, and followed the contributing guidelines.

AI Assistance

• Yes
• No

If you answered "yes" above, how did you use AI assistance?

• Code generation (e.g., when writing an implementation or fixing a bug)
• Test/benchmark generation
• Documentation (including examples)
• Research and understanding

Disclosure

This PR was authored by Claude Code as part of an automated cross-package drift-detection routine. The routine selected the stats/array namespace at random (seed 1777451199), extracted structural and semantic features for every member, computed majority patterns at a 75% conformance threshold, ran three independent validation agents, and applied only mechanical JSDoc reorderings whose correctness all three validators confirmed. Each commit is one outlier package.

---

@stdlib-js/reviewers

---

Generated by Claude Code

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
stats/array/nanstdev	$\color{green}123/123$ $\color{green}+100.00%$	$\color{green}12/12$ $\color{green}+100.00%$	$\color{green}1/1$ $\color{green}+100.00%$	$\color{green}123/123$ $\color{green}+100.00%$
stats/array/nanstdevch	$\color{green}123/123$ $\color{green}+100.00%$	$\color{green}12/12$ $\color{green}+100.00%$	$\color{green}1/1$ $\color{green}+100.00%$	$\color{green}123/123$ $\color{green}+100.00%$
stats/array/nanstdevpn	$\color{green}123/123$ $\color{green}+100.00%$	$\color{green}12/12$ $\color{green}+100.00%$	$\color{green}1/1$ $\color{green}+100.00%$	$\color{green}123/123$ $\color{green}+100.00%$
stats/array/nanstdevtk	$\color{green}123/123$ $\color{green}+100.00%$	$\color{green}12/12$ $\color{green}+100.00%$	$\color{green}1/1$ $\color{green}+100.00%$	$\color{green}123/123$ $\color{green}+100.00%$
stats/array/nanstdevwd	$\color{green}123/123$ $\color{green}+100.00%$	$\color{green}12/12$ $\color{green}+100.00%$	$\color{green}1/1$ $\color{green}+100.00%$	$\color{green}123/123$ $\color{green}+100.00%$
stats/array/nanstdevyc	$\color{green}123/123$ $\color{green}+100.00%$	$\color{green}12/12$ $\color{green}+100.00%$	$\color{green}1/1$ $\color{green}+100.00%$	$\color{green}123/123$ $\color{green}+100.00%$
stats/array/stdev	$\color{green}123/123$ $\color{green}+100.00%$	$\color{green}12/12$ $\color{green}+100.00%$	$\color{green}1/1$ $\color{green}+100.00%$	$\color{green}123/123$ $\color{green}+100.00%$
stats/array/stdevch	$\color{green}123/123$ $\color{green}+100.00%$	$\color{green}12/12$ $\color{green}+100.00%$	$\color{green}1/1$ $\color{green}+100.00%$	$\color{green}123/123$ $\color{green}+100.00%$
stats/array/stdevpn	$\color{green}123/123$ $\color{green}+100.00%$	$\color{green}12/12$ $\color{green}+100.00%$	$\color{green}1/1$ $\color{green}+100.00%$	$\color{green}123/123$ $\color{green}+100.00%$
stats/array/stdevtk	$\color{green}123/123$ $\color{green}+100.00%$	$\color{green}12/12$ $\color{green}+100.00%$	$\color{green}1/1$ $\color{green}+100.00%$	$\color{green}123/123$ $\color{green}+100.00%$
stats/array/stdevwd	$\color{green}123/123$ $\color{green}+100.00%$	$\color{green}12/12$ $\color{green}+100.00%$	$\color{green}1/1$ $\color{green}+100.00%$	$\color{green}123/123$ $\color{green}+100.00%$
stats/array/stdevyc	$\color{green}123/123$ $\color{green}+100.00%$	$\color{green}12/12$ $\color{green}+100.00%$	$\color{green}1/1$ $\color{green}+100.00%$	$\color{green}123/123$ $\color{green}+100.00%$

The above coverage report was generated for the changes in this PR.