Skip to content

docs: correct scale parameter JSDoc type in stats/base/dists/levy#12027

Merged
kgryte merged 2 commits intodevelopfrom
claude/inspiring-curie-DFzWS
May 9, 2026
Merged

docs: correct scale parameter JSDoc type in stats/base/dists/levy#12027
kgryte merged 2 commits intodevelopfrom
claude/inspiring-curie-DFzWS

Conversation

@Planeshifter
Copy link
Copy Markdown
Member

Description

What is the purpose of this pull request?

This pull request tightens the JSDoc @param annotation for the scale parameter c in two outlier packages within @stdlib/stats/base/dists/levy/* so that the documented type matches the runtime behavior and the rest of the namespace.

Namespace summary

  • Members analyzed: 12 non-autogenerated packages (cdf, ctor, entropy, logcdf, logpdf, mean, median, mode, pdf, quantile, stdev, variance).
  • Features analyzed: file tree, package.json shape, README headings, manifest.json shape, test/benchmark/example file naming, public signatures, validation prologues, error construction, JSDoc shape, and source dependencies.
  • Features with a clear majority (≥75%) producing actionable drift findings: JSDoc @param type for the scale parameter c.
  • Features with no clear majority or where deviations were semantically justified (and excluded): native binding presence (the ctor package legitimately has no native addon), R benchmark files (present only in distribution-function packages), Julia test fixtures (varies by package; not mechanically synthesizable), lib/factory.js presence (only relevant for distribution-function packages), and ## Notes README section (specific to packages with non-trivial domain notes).

Per outlier package

@stdlib/stats/base/dists/levy/quantile

Corrects the JSDoc @param annotation for the scale parameter c in lib/main.js, lib/factory.js, and lib/native.js from NonNegativeNumber to PositiveNumber. The runtime guard returns NaN for c <= 0.0, so zero is not a valid input and the looser annotation was incorrect. Brings this package into alignment with the 11 other Lévy distribution packages that already use PositiveNumber for c (92% conformance).

@stdlib/stats/base/dists/levy/cdf

Corrects the JSDoc type annotation for the scale parameter c in lib/native.js from {number} to {PositiveNumber}, bringing the native binding wrapper into conformance with the 82% majority pattern across analogous wrappers and with lib/main.js, which already documents the parameter correctly. The looser {number} annotation is inaccurate: the runtime returns NaN for c <= 0, so PositiveNumber is the precise type. No logic changes.

Validation

Checked via:

  • Structural feature extraction across all 12 non-autogenerated namespace members (file trees, package.json shape, README headings, manifest.json shape, test/benchmark/example file naming).
  • Per-package semantic feature extraction (public signature, validation prologue, error construction, JSDoc shape, dependencies).
  • Three-agent drift validation: semantic review (confirmed the JSDoc type mismatch is a documentation oversight, not a behavioral difference), cross-reference review (confirmed no test, type-test, example, or sibling package depends on the deviating JSDoc text — docs/types/index.d.ts declarations use bare number and tests verify runtime behavior via tape), and structural review (n/a; the change is a JSDoc tag edit, not a structural addition).

Deliberately excluded:

  • Outliers reflecting a genuine semantic difference (e.g., ctor lacking native binding files because it is a class constructor, not a math function).
  • Drift requiring non-mechanical fixes (e.g., adding Julia test fixtures, which would require generating reference data).
  • Features without a clear majority pattern.

Related Issues

Does this pull request have any related issues?

No.

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.

Total diff: 4 lines across 4 files in 2 outlier packages. Each commit groups all corrections per outlier package.

Checklist

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

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

This PR was authored by Claude Code via an automated cross-package API drift detection routine. The routine extracts structural and semantic features from every non-autogenerated package in a randomly selected stdlib namespace, identifies the majority pattern per feature, and flags deviating packages. Proposed corrections were validated by three independent agents (semantic review, cross-reference review, structural review) before being applied. All applied changes are mechanical JSDoc type corrections that preserve runtime behavior.


Generated by Claude Code

claude added 2 commits May 9, 2026 20:16
The JSDoc `@param` tag for the scale parameter `c` was annotated as
`NonNegativeNumber` in `lib/main.js`, `lib/factory.js`, and
`lib/native.js`. The runtime guard rejects `c <= 0.0` (returning
`NaN`), so `c = 0` is not a valid input and the correct annotation is
`PositiveNumber`. The remaining 11 packages in
`@stdlib/stats/base/dists/levy/*` consistently use `PositiveNumber`
for `c` (92% conformance).
The native binding wrapper documented the scale parameter `c` with
the loose JSDoc type `number`, while the corresponding `lib/main.js`
and the rest of the namespace use `PositiveNumber` (82% conformance
across native binding wrappers in the same namespace). The runtime
returns `NaN` for `c <= 0.0`, so `PositiveNumber` is the type that
matches actual behavior.
@stdlib-bot stdlib-bot added the Statistics Issue or pull request related to statistical functionality. label May 9, 2026
@stdlib-bot
Copy link
Copy Markdown
Contributor

Coverage Report

Package Statements Branches Functions Lines
stats/base/dists/levy/cdf $\color{green}310/310$
$\color{green}+100.00%$
$\color{green}23/23$
$\color{green}+100.00%$
$\color{green}4/4$
$\color{green}+100.00%$
$\color{green}310/310$
$\color{green}+100.00%$
stats/base/dists/levy/quantile $\color{green}295/295$
$\color{green}+100.00%$
$\color{green}23/23$
$\color{green}+100.00%$
$\color{green}4/4$
$\color{green}+100.00%$
$\color{green}295/295$
$\color{green}+100.00%$

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

@Planeshifter Planeshifter marked this pull request as ready for review May 9, 2026 20:58
@Planeshifter Planeshifter requested review from a team and kgryte May 9, 2026 20:58
@stdlib-bot stdlib-bot added the Needs Review A pull request which needs code review. label May 9, 2026
@kgryte kgryte added Documentation Improvements, additions, or changes to documentation. and removed Needs Review A pull request which needs code review. labels May 9, 2026
@kgryte kgryte merged commit 04ea19c into develop May 9, 2026
71 checks passed
@kgryte kgryte deleted the claude/inspiring-curie-DFzWS branch May 9, 2026 22:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Documentation Improvements, additions, or changes to documentation. Statistics Issue or pull request related to statistical functionality.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants