docs: correct @throws description for pulse duration

[Planeshifter]

Description

Five window-pulse packages under @stdlib/simulate/iter carry a stale @throws JSDoc tag whose text contradicts the runtime guard, the thrown error message, and the corresponding test description. This pull request updates the tag in each package to match the actual implemented behavior. No runtime, type, test, or example changes.

Namespace summary

• Namespace: @stdlib/simulate/iter
• Members analyzed: 16 (all non-autogenerated).
• Features analyzed: file tree, package.json shape, manifest.json shape, README section sequences, test/benchmark/examples filenames, public signatures, return kind, validation prologue, error construction, JSDoc shape, dependency sets, TypeScript declarations.
• Features with a clear majority (≥75% conformance): all 18 package.json top-level keys (16/16); README L2 sequence (Usage, Notes, Examples, See Also) (16/16); README HTML <section> divs (intro, usage, notes, examples, references, related, links) (16/16); test/test.js, benchmark/benchmark.js, examples/index.js, docs/types/index.d.ts, docs/types/test.ts (16/16 each); errorConstruction: format (16/16); returnKind: iterator (16/16); lib/validate.js (13/16, present in all packages whose validation is purely options-shaped).
• Features excluded for no clear majority: main publicSignature (varies by package semantic surface — pure-options vs noise-iterator-positional vs periodic-sinc/n); JSDoc @throws set (varies); trailing README reference-link counts (manually curated).
• Features with a clear majority that were excluded for cause: TypeScript return type (13/16 Iterator, 3/16 ExtendedIterator) — ExtendedIterator reflects the runtime PRNG-state surface on the 3 noise iterators and is intentional; lib/validate.js absence in awgn/awln/awun — intentional, those packages interleave positional and options validation in a fixed order that defines the public-error contract.

simulate/iter/bartlett-hann-pulse

The @throws tag at lib/main.js:68 documented pulse duration must be less than the period, but the runtime guard at lib/main.js:114 is if ( opts.duration > opts.period ), the thrown RangeError says "less than or equal to the period", and the test title says "greater than the pulse period". The -1 sentinel default at :113 assigns opts.duration = opts.period, which would immediately throw under a strict-< guard — proof that the inclusive guard is intentional. JSDoc updated to match.

simulate/iter/bartlett-pulse

The @throws tag at lib/main.js:43 documented pulse duration must be less than the period, but the runtime guard at lib/main.js:90 is > and the thrown RangeError says "less than or equal to the period". The -1 sentinel default at :88 assigns opts.duration = opts.period, which would immediately throw under a strict-< guard. JSDoc updated to match.

simulate/iter/flat-top-pulse

The @throws tag at lib/main.js:69 documented pulse duration must be less than the period, but the runtime guard at lib/main.js:115 is > and the thrown RangeError says "less than or equal to the period". The -1 sentinel default at :114 assigns opts.duration = opts.period, which would immediately throw under a strict-< guard. JSDoc updated to match.

simulate/iter/hann-pulse

The @throws tag at lib/main.js:43 documented pulse duration must be less than the period, but the runtime guard at lib/main.js:91 is > and the thrown RangeError says "less than or equal to the period". The -1 sentinel default at :89 assigns opts.duration = opts.period, which would immediately throw under a strict-< guard. JSDoc updated to match.

simulate/iter/lanczos-pulse

The @throws tag at lib/main.js:43 documented pulse duration must be less than the period, but the runtime guard at lib/main.js:90 is > and the thrown RangeError says "less than or equal to the period". The -1 sentinel default at :88 assigns opts.duration = opts.period, which would immediately throw under a strict-< guard. JSDoc updated to match.

Note on the sibling simulate/iter/pulse package

pulse is a square pulse whose formula returns max when t < duration and min otherwise. A square pulse with duration == period is degenerate (constant max, no return to min), so its strict-< guard at lib/main.js:90 and its @throws text are internally consistent and correct. It is deliberately not modified.

Related Issues

This pull request does not have any related issues.

Questions

No.

Other

Validation

What was checked:

• Structural feature extraction across all 16 namespace members (file tree, package.json / manifest.json shape, README section sequences, test/benchmark/examples filenames, TypeScript declaration shape).
• Semantic feature extraction across all 16 lib/main.js files (public signature, return kind, validation prologue, error construction, JSDoc shape, dependencies).
• Three-agent drift validation on the candidate correction:
  • Semantic-review agent (opus): confirmed for all 5 packages that the -1 sentinel default would throw under a >= guard, and that all five window functions are mathematically well-defined at duration == period. The inclusive guard is intentional; the JSDoc text is stale.
  • Cross-reference agent (opus): confirmed for all 5 packages that no test asserts on the JSDoc text, no example relies on the strict-< interpretation, and no sibling or namespace-level doc reproduces the @throws text. The sibling pulse package is internally consistent at strict-< and is correctly excluded from the fix.
  • Structural-review agent (sonnet): confirmed for all 5 packages that the proposed text matches the existing thrown RangeError message exactly, and that no other @throws tag in the same JSDoc block needs adjustment.

What was deliberately excluded:

• lib/validate.js absence in awgn/awln/awun (13/16 majority): intentional. Noise iterators interleave positional (iterator, sigma) and options validation in a fixed error-firing order; factoring this into a helper would change the contract.
• TypeScript declaration ExtendedIterator vs Iterator (13/16 majority): intentional. The 3 noise iterators expose runtime PRNG-state properties (PRNG, seed, state, seedLength, stateLength, byteLength) that the wave iterators don't have.
• [options.period] JSDoc text drift in sine-wave/cosine-wave (10/13 say "a waveform repeats"; sine/cosine say "a sine/cosine wave repeats"): the deviation appears identically in lib/main.js, lib/validate.js, docs/types/index.d.ts, docs/repl.txt, and README.md; the .d.ts and repl.txt files are protected from automated edits, so the fix cannot be made internally consistent within a single package and was dropped. Also overlaps with cosine-wave/README.md work in docs: add cosine wave visualization to simulate/iter/cosine-wave #9599.
• dirac-comb/lib/main.js:81 inline normalize comment uses [0,T] instead of [0,τ] (5/6 use τ): T is the canonical period symbol in Dirac-comb literature; treated as intentional notation.
• Sub-majority intra-cluster divergence: awgn sets PRNG: null when an external PRNG is provided; awln/awun set PRNG: options.prng. Real inconsistency, but invisible to the 16-member majority vote (2/3 within the 3-noise sub-cluster, sub-75% across the namespace). Belongs to a future cluster-internal drift pass.
• awgn/awln/awun READMEs lack ` math blocks (13/16 have them): the noise iterators have no closed-form waveform worth typesetting.

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 API drift-detection routine on a randomly picked stdlib namespace. Structural and semantic features were extracted across all 16 non-autogenerated members of @stdlib/simulate/iter; the single high-signal finding (stale @throws text contradicting the actual runtime behavior in 5 window-pulse packages) was validated by three parallel review agents (opus semantic-review, opus cross-reference, sonnet structural-review), all returning confirmed-drift for all five outliers. The applied fix is a one-line JSDoc text update per package with no runtime, type, test, or example changes.

---

@stdlib-js/reviewers

---

Generated by Claude Code

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
simulate/iter/bartlett-hann-pulse	$\color{green}343/343$ $\color{green}+100.00\%$	$\color{green}44/44$ $\color{green}+100.00\%$	$\color{green}6/6$ $\color{green}+100.00\%$	$\color{green}343/343$ $\color{green}+100.00\%$
simulate/iter/bartlett-pulse	$\color{green}320/320$ $\color{green}+100.00\%$	$\color{green}43/43$ $\color{green}+100.00\%$	$\color{green}5/5$ $\color{green}+100.00\%$	$\color{green}320/320$ $\color{green}+100.00\%$
simulate/iter/flat-top-pulse	$\color{green}344/344$ $\color{green}+100.00\%$	$\color{green}44/44$ $\color{green}+100.00\%$	$\color{green}6/6$ $\color{green}+100.00\%$	$\color{green}344/344$ $\color{green}+100.00\%$
simulate/iter/hann-pulse	$\color{green}322/322$ $\color{green}+100.00\%$	$\color{green}43/43$ $\color{green}+100.00\%$	$\color{green}5/5$ $\color{green}+100.00\%$	$\color{green}322/322$ $\color{green}+100.00\%$
simulate/iter/lanczos-pulse	$\color{green}320/320$ $\color{green}+100.00\%$	$\color{green}43/43$ $\color{green}+100.00\%$	$\color{green}5/5$ $\color{green}+100.00\%$	$\color{green}320/320$ $\color{green}+100.00\%$

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