docs: fix inconsistent JSDoc annotations

[Planeshifter]

Description

What is the purpose of this pull request?

This pull request corrects three drifted JSDoc annotations in random/base distribution samplers, normalizing each outlier to the convention shared by the rest of the namespace. No runtime behavior, signatures, or tests change.

Namespace summary

• Members analyzed: 43 (random/base direct children with a package.json) — 33 distribution samplers plus 10 PRNG engines/utilities (mt19937, minstd, minstd-shuffle, box-muller, improved-ziggurat, randi, randn, randu, reviver, shared).
• Features analyzed: file tree, package.json shape, README section list/order, manifest.json shape, and test/benchmark/examples naming (structural); public signature, return kind, validation prologue, error construction, JSDoc shape, and dependencies (semantic).
• Features with a clear majority (≥75%, i.e. ≥33/43): error construction (100% use format), package.json top-level keys, README section set and order, benchmark/test/examples file sets, factory @returns/option JSDoc types, the @name generator tag (37/43), the @type {PRNG} generator annotation (40/43), and the "scale parameter" description convention.
• Features without a clear majority (excluded): lib/validate.js presence (25/43 = 58% — absence tracks single-parameter distributions, a semantic difference, not drift); package.json scripts/stdlib sub-keys; per-package return type (discrete distributions return integers, continuous return numbers — semantic).

random/base/chisquare

The top-level generator in lib/main.js carried @function chisquare while being an assigned PRNG value tagged @type {PRNG}. Distribution samplers document the bound generator with @name (32/33 samplers; 37/43 members); @function belongs to the PRNG-engine cluster (minstd, minstd-shuffle, mt19937). Retagged to @name chisquare.

random/base/rayleigh

The generator in lib/main.js was annotated @type {Function} — the only such case in the namespace. 40/43 members annotate the factory()-returned generator with the more specific @type {PRNG}, and rayleigh already used @name rayleigh. Narrowed the stale generic annotation to @type {PRNG}.

random/base/gumbel

lib/validate.js described beta as the "shape parameter", contradicting the package's own lib/factory.js and lib/main.js (both "scale parameter") and every scale-family sibling (invgamma, laplace, logistic, lognormal, weibull, frechet). The Gumbel distribution is parameterized by location and scale only. Corrected to "scale parameter".

Related Issues

Does this pull request have any related issues?

No related issues.

Questions

Any questions for reviewers of this pull request?

No.

Other

Any other information relevant to this pull request? This may include screenshots, references, and/or implementation notes.

Corrections were selected by a cross-package majority-vote drift analysis over all 43 random/base members and validated by a three-pass review (semantic-review, cross-reference against tests/examples, and structural-review). Each surviving correction is confirmed drift, is mechanical, and is behavior-preserving with no test or example dependency.

Deliberately excluded:

• The PRNG-engine @function cluster (minstd, minstd-shuffle, mt19937) — an intentional engine convention, not drift.
• lib/validate.js absence in single-parameter samplers (bernoulli, chi, chisquare, exponential, geometric, poisson, rayleigh, t) — a semantic difference (single inline check vs. a shared multi-parameter helper).
• Features without a clear ≥75% majority.

One additional finding is noted but not included here: random/base/binomial lib/validate.js interpolates the wrong variable (p instead of n) in its first-argument error message, so an invalid n currently reports p's value. It is confirmed drift against the unanimous sibling convention (each check interpolates the argument it validates), but the fix alters a runtime diagnostic string (observable behavior) and is therefore out of scope for this docs-only PR. Flagging for maintainer follow-up.

Checklist

Please ensure the following tasks are completed before submitting this pull request.

• Read, understood, and followed the contributing guidelines.

AI Assistance

When authoring the changes proposed in this PR, did you use any kind of 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

If you answered "yes" to using AI assistance, please provide a short disclosure indicating how you used AI assistance. This helps reviewers determine how much scrutiny to apply when reviewing your contribution.

This PR was authored by Claude Code running an automated cross-package drift-detection routine. It extracted structural and semantic features across all 43 random/base members, computed the per-feature majority convention, and applied the three JSDoc corrections above to the outlier packages. A three-agent validation pass confirmed each correction as unintentional drift with no behavioral or test impact, and each modified line was re-read against its siblings before committing.

---

@stdlib-js/reviewers

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01Hcthcf81vj8b3zxDKoJRsT

---

Generated by Claude Code

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
random/base/chisquare	$\\color{green}375/375$ $\\color{green}+100.00\\%$	$\\color{green}44/44$ $\\color{green}+100.00\\%$	$\\color{green}10/10$ $\\color{green}+100.00\\%$	$\\color{green}375/375$ $\\color{green}+100.00\\%$
random/base/gumbel	$\\color{green}493/493$ $\\color{green}+100.00\\%$	$\\color{green}55/55$ $\\color{green}+100.00\\%$	$\\color{green}12/12$ $\\color{green}+100.00\\%$	$\\color{green}493/493$ $\\color{green}+100.00\\%$
random/base/rayleigh	$\\color{green}430/430$ $\\color{green}+100.00\\%$	$\\color{green}46/46$ $\\color{green}+100.00\\%$	$\\color{green}11/11$ $\\color{green}+100.00\\%$	$\\color{green}430/430$ $\\color{green}+100.00\\%$

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