Skip to content

docs: fix TSDoc issues across many math/base/special declarations#12467

Draft
Planeshifter wants to merge 1 commit into
developfrom
philipp/docs-fix-base-special-declarations
Draft

docs: fix TSDoc issues across many math/base/special declarations#12467
Planeshifter wants to merge 1 commit into
developfrom
philipp/docs-fix-base-special-declarations

Conversation

@Planeshifter
Copy link
Copy Markdown
Member

@Planeshifter Planeshifter commented Jun 2, 2026 •
edited
Loading

Description

What is the purpose of this pull request?

This pull request corrects documentation-only issues in TypeScript declaration files across many @stdlib/math/base/special packages, flagged by an audit. No emitted types change in a behavior-affecting way; the edits are limited to TSDoc prose, examples, parameter names/descriptions, and internal interface names.

Highlights:

  • kernel-betainc — the 4th/5th parameters were named invert/normalized with descriptions swapped relative to the implementation kernelBetainc( x, a, b, regularized, upper ); renamed to regularized/upper with descriptions re-paired, fixed the garbled "regularized boolean beta function" → "incomplete beta function" (in the declaration and the lib/main.js/lib/assign.js JSDoc), and fixed the interface doc-comment misspelling kernalBetaInc.
  • gammainc — split the muddled regularized/upper Notes into two clear bullets and fixed a stale s <= 0 → a <= 0 reference.
  • cfloor — summary now reads "Rounds each component of..." like its siblings; cpolarf/sincosd — fixed copy-pasted/lowercase interface names (Cpolar → Cpolarf, sincosd → SinCosd).
  • minmax/minmaxn/minmaxf/sincospi — assign @examples now call the .assign method instead of the bare function (so v === out is actually true); corrected the assign summary/@returns for sincospi; split merged @example blocks.
  • minabs — dropped the empty-set Notes paragraph (the function is binary); minabsn/maxabsn/minmaxabsn — corrected the empty-args identity Notes.
  • covercos/coversin/havercos — added the defining-formula Notes block their forward-trig siblings include.
  • Assorted prose fixes: frexp/frexpf "Inteface" typo; absf/acsch/asech/negalucasf summary wording; floorn summary ("numeric value", matching ceiln/roundn/truncn); cotd/tand trailing periods; cround unused requires; gammaincinv argument-order notation; lnf/round @returns; truncsd/binomcoef/fast/hypot/fast/hypotf @param descriptions; gamma-lanczos-sum-expg-scaled unbalanced parenthesis; sind example spacing; fast/maxf stray blank line; and a few missing @example tags and interface doc comments.

This PR addresses the TypeScript declarations (plus the kernel-betainc lib JSDoc, to keep that package's fix whole); the generated namespace aggregator will pick up these fixes on regeneration. Several findings that are errors replicated across a package's other doc surfaces — cscd, nonfibonaccif, nonfibonacci, powf — are handled package-wide in a separate PR (#12474). The non-docs fresnel return-type narrowing and higher-severity ellipj/factorial2f fixes are in their own PRs.

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?

Found via a TypeScript-declaration audit of the @stdlib/math namespace. Several findings were verified against the package implementations (e.g. kernel-betainc, gammainc).

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

If you answered "yes" to using AI assistance, please provide a short disclosure.

These issues were identified by an automated TypeScript-declaration audit run with Claude Code, and the fixes were prepared by Claude Code (with parallel sub-agents per package group) under my review.

@stdlib-js/reviewers

@stdlib-bot stdlib-bot added the Math Issue or pull request specific to math functionality. label Jun 2, 2026
@stdlib-bot
Copy link
Copy Markdown
Contributor

stdlib-bot commented Jun 2, 2026 •
edited
Loading

Coverage Report

Package Statements Branches Functions Lines
math/base/special/absf $\color{green}241/241$
$\color{green}+0.00\%$ 		$\color{green}7/7$
$\color{green}+0.00\%$ 		$\color{green}3/3$
$\color{green}+0.00\%$ 		$\color{green}241/241$
$\color{green}+0.00\%$
math/base/special/acsch $\color{green}157/157$
$\color{green}+0.00\%$ 		$\color{green}5/5$
$\color{green}+0.00\%$ 		$\color{green}2/2$
$\color{green}+0.00\%$ 		$\color{green}157/157$
$\color{green}+0.00\%$
math/base/special/asech $\color{green}160/160$
$\color{green}+0.00\%$ 		$\color{green}5/5$
$\color{green}+0.00\%$ 		$\color{green}2/2$
$\color{green}+0.00\%$ 		$\color{green}160/160$
$\color{green}+0.00\%$
math/base/special/binomcoef $\color{green}269/269$
$\color{green}+0.00\%$ 		$\color{green}34/34$
$\color{green}+0.00\%$ 		$\color{green}2/2$
$\color{green}+0.00\%$ 		$\color{green}269/269$
$\color{green}+0.00\%$
math/base/special/cfloor $\color{green}180/180$
$\color{green}+0.00\%$ 		$\color{green}5/5$
$\color{green}+0.00\%$ 		$\color{green}2/2$
$\color{green}+0.00\%$ 		$\color{green}180/180$
$\color{green}+0.00\%$
math/base/special/cotd $\color{green}176/176$
$\color{green}+0.00\%$ 		$\color{green}5/5$
$\color{green}+0.00\%$ 		$\color{green}2/2$
$\color{green}+0.00\%$ 		$\color{green}176/176$
$\color{green}+0.00\%$
math/base/special/covercos $\color{green}164/164$
$\color{green}+0.00\%$ 		$\color{green}5/5$
$\color{green}+0.00\%$ 		$\color{green}2/2$
$\color{green}+0.00\%$ 		$\color{green}164/164$
$\color{green}+0.00\%$
math/base/special/coversin $\color{green}164/164$
$\color{green}+0.00\%$ 		$\color{green}5/5$
$\color{green}+0.00\%$ 		$\color{green}2/2$
$\color{green}+0.00\%$ 		$\color{green}164/164$
$\color{green}+0.00\%$
math/base/special/cpolarf $\color{green}212/212$
$\color{green}+0.00\%$ 		$\color{green}7/7$
$\color{green}+0.00\%$ 		$\color{green}3/3$
$\color{green}+0.00\%$ 		$\color{green}212/212$
$\color{green}+0.00\%$
math/base/special/cround $\color{green}161/161$
$\color{green}+0.00\%$ 		$\color{green}5/5$
$\color{green}+0.00\%$ 		$\color{green}2/2$
$\color{green}+0.00\%$ 		$\color{green}161/161$
$\color{green}+0.00\%$
math/base/special/fast/hypot $\color{green}133/133$
$\color{green}+0.00\%$ 		$\color{green}5/5$
$\color{green}+0.00\%$ 		$\color{green}2/2$
$\color{green}+0.00\%$ 		$\color{green}133/133$
$\color{green}+0.00\%$
math/base/special/fast/hypotf $\color{green}136/136$
$\color{green}+0.00\%$ 		$\color{green}5/5$
$\color{green}+0.00\%$ 		$\color{green}2/2$
$\color{green}+0.00\%$ 		$\color{green}136/136$
$\color{green}+0.00\%$
math/base/special/fast/maxf $\color{green}182/182$
$\color{green}+0.00\%$ 		$\color{green}7/7$
$\color{green}+0.00\%$ 		$\color{green}2/2$
$\color{green}+0.00\%$ 		$\color{green}182/182$
$\color{green}+0.00\%$
math/base/special/floorn $\color{green}272/272$
$\color{green}+0.00\%$ 		$\color{green}24/24$
$\color{green}+0.00\%$ 		$\color{green}2/2$
$\color{green}+0.00\%$ 		$\color{green}272/272$
$\color{green}+0.00\%$
math/base/special/frexp $\color{green}329/329$
$\color{green}+0.00\%$ 		$\color{green}11/11$
$\color{green}+0.00\%$ 		$\color{green}3/3$
$\color{green}+0.00\%$ 		$\color{green}329/329$
$\color{green}+0.00\%$
math/base/special/frexpf $\color{green}328/328$
$\color{green}+0.00\%$ 		$\color{green}11/11$
$\color{green}+0.00\%$ 		$\color{green}3/3$
$\color{green}+0.00\%$ 		$\color{green}328/328$
$\color{green}+0.00\%$
math/base/special/gamma-lanczos-sum-expg-scaled $\color{red}255/258$
$\color{green}+0.00\%$ 		$\color{red}8/10$
$\color{green}+0.00\%$ 		$\color{green}2/2$
$\color{green}+0.00\%$ 		$\color{red}255/258$
$\color{green}+0.00\%$
math/base/special/gammainc $\color{red}1755/1978$
$\color{green}+0.00\%$ 		$\color{red}124/155$
$\color{green}+0.00\%$ 		$\color{red}21/27$
$\color{green}+0.00\%$ 		$\color{red}1755/1978$
$\color{green}+0.00\%$
math/base/special/gammaincinv $\color{red}1590/1821$
$\color{green}+0.00\%$ 		$\color{red}124/153$
$\color{green}+0.00\%$ 		$\color{red}14/23$
$\color{green}+0.00\%$ 		$\color{red}1590/1821$
$\color{green}+0.00\%$
math/base/special/havercos $\color{green}164/164$
$\color{green}+0.00\%$ 		$\color{green}5/5$
$\color{green}+0.00\%$ 		$\color{green}2/2$
$\color{green}+0.00\%$ 		$\color{green}164/164$
$\color{green}+0.00\%$
math/base/special/kernel-betainc $\color{red}931/1730$
$\color{green}+0.00\%$ 		$\color{red}29/39$
$\color{green}+0.00\%$ 		$\color{red}2/13$
$\color{green}+0.00\%$ 		$\color{red}931/1730$
$\color{green}+0.00\%$
math/base/special/lnf $\color{green}376/376$
$\color{green}+0.00\%$ 		$\color{green}35/35$
$\color{green}+0.00\%$ 		$\color{green}4/4$
$\color{green}+0.00\%$ 		$\color{green}376/376$
$\color{green}+0.00\%$
math/base/special/maxabsn $\color{green}125/125$
$\color{green}+0.00\%$ 		$\color{green}9/9$
$\color{green}+0.00\%$ 		$\color{green}1/1$
$\color{green}+0.00\%$ 		$\color{green}125/125$
$\color{green}+0.00\%$
math/base/special/minabs $\color{green}160/160$
$\color{green}+0.00\%$ 		$\color{green}5/5$
$\color{green}+0.00\%$ 		$\color{green}2/2$
$\color{green}+0.00\%$ 		$\color{green}160/160$
$\color{green}+0.00\%$
math/base/special/minabsn $\color{green}125/125$
$\color{green}+0.00\%$ 		$\color{green}8/8$
$\color{green}+0.00\%$ 		$\color{green}1/1$
$\color{green}+0.00\%$ 		$\color{green}125/125$
$\color{green}+0.00\%$
math/base/special/minmax $\color{green}253/253$
$\color{green}+0.00\%$ 		$\color{green}17/17$
$\color{green}+0.00\%$ 		$\color{green}3/3$
$\color{green}+0.00\%$ 		$\color{green}253/253$
$\color{green}+0.00\%$
math/base/special/minmaxabsn $\color{green}255/255$
$\color{green}+0.00\%$ 		$\color{green}24/24$
$\color{green}+0.00\%$ 		$\color{green}2/2$
$\color{green}+0.00\%$ 		$\color{green}255/255$
$\color{green}+0.00\%$
math/base/special/minmaxf $\color{green}253/253$
$\color{green}+0.00\%$ 		$\color{green}17/17$
$\color{green}+0.00\%$ 		$\color{green}3/3$
$\color{green}+0.00\%$ 		$\color{green}253/253$
$\color{green}+0.00\%$
math/base/special/minmaxn $\color{green}267/267$
$\color{green}+0.00\%$ 		$\color{green}35/35$
$\color{green}+0.00\%$ 		$\color{green}2/2$
$\color{green}+0.00\%$ 		$\color{green}267/267$
$\color{green}+0.00\%$
math/base/special/negalucasf $\color{green}221/221$
$\color{green}+0.00\%$ 		$\color{green}11/11$
$\color{green}+0.00\%$ 		$\color{green}2/2$
$\color{green}+0.00\%$ 		$\color{green}221/221$
$\color{green}+0.00\%$
math/base/special/round $\color{green}236/236$
$\color{green}+0.00\%$ 		$\color{green}4/4$
$\color{green}+0.00\%$ 		$\color{green}1/1$
$\color{green}+0.00\%$ 		$\color{green}236/236$
$\color{green}+0.00\%$
math/base/special/sincosd $\color{green}249/249$
$\color{green}+0.00\%$ 		$\color{green}7/7$
$\color{green}+0.00\%$ 		$\color{green}3/3$
$\color{green}+0.00\%$ 		$\color{green}249/249$
$\color{green}+0.00\%$
math/base/special/sincospi $\color{green}296/296$
$\color{green}+0.00\%$ 		$\color{green}23/23$
$\color{green}+0.00\%$ 		$\color{green}3/3$
$\color{green}+0.00\%$ 		$\color{green}296/296$
$\color{green}+0.00\%$
math/base/special/sind $\color{green}202/202$
$\color{green}+0.00\%$ 		$\color{green}20/20$
$\color{green}+0.00\%$ 		$\color{green}2/2$
$\color{green}+0.00\%$ 		$\color{green}202/202$
$\color{green}+0.00\%$
math/base/special/tand $\color{green}165/165$
$\color{green}+0.00\%$ 		$\color{green}5/5$
$\color{green}+0.00\%$ 		$\color{green}2/2$
$\color{green}+0.00\%$ 		$\color{green}165/165$
$\color{green}+0.00\%$
math/base/special/truncsd $\color{green}219/219$
$\color{green}+0.00\%$ 		$\color{green}27/27$
$\color{green}+0.00\%$ 		$\color{green}2/2$
$\color{green}+0.00\%$ 		$\color{green}219/219$
$\color{green}+0.00\%$

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

@Planeshifter Planeshifter force-pushed the philipp/docs-fix-base-special-declarations branch 2 times, most recently from ee5bdc1 to 796b024 Compare June 3, 2026 00:32
@Planeshifter Planeshifter mentioned this pull request Jun 3, 2026
Merged
7 tasks
@Planeshifter
docs: fix TSDoc issues across many @stdlib/math/base/special declar…
395f690 
…ations

Correct documentation-only issues in the TypeScript declaration files
flagged by an audit of the `@stdlib/math/base/special` namespace. No
emitted types change in a behavior-affecting way; the edits are limited
to TSDoc prose, examples, parameter names/descriptions, and internal
interface names.

Highlights:

- `kernel-betainc`: the 4th/5th parameters were named `invert`/
  `normalized` with descriptions swapped relative to the implementation
  `kernelBetainc( x, a, b, regularized, upper )`; rename to
  `regularized`/`upper` and re-pair the descriptions, fix the garbled
  "regularized boolean beta function" -> "incomplete beta function" (in
  the declaration and the `lib/main.js`/`lib/assign.js` JSDoc), and fix
  the interface doc comment misspelling `kernalBetaInc`.
- `gammainc`: split the muddled `regularized`/`upper` Notes into two
  clear bullets and fix a stale `s <= 0` -> `a <= 0` reference.
- `cfloor`: summary now says "Rounds each component of..." like its
  siblings; `cpolarf`/`sincosd`: fix copy-pasted/lowercase interface
  names (`Cpolar` -> `Cpolarf`, `sincosd` -> `SinCosd`).
- `minmax`/`minmaxn`/`minmaxf`/`sincospi`: `assign` `@example`s now call
  the `.assign` method instead of the bare function (so `v === out` is
  actually `true`); correct the `assign` summary/`@returns` for
  `sincospi`; split merged `@example` blocks.
- `minabs`: drop the empty-set Notes paragraph (the function is binary);
  `minabsn`/`maxabsn`/`minmaxabsn`: correct the empty-args identity
  Notes (a minimum's bound is the greatest *lower* bound; the absolute
  maximum's empty result follows from the `-infinity` identity).
- `covercos`/`coversin`/`havercos`: add the defining-formula Notes block
  their forward-trig siblings include.
- Assorted prose fixes: `frexp`/`frexpf` "Inteface" typo, `absf`/
  `acsch`/`asech`/`negalucasf` summary wording, `floorn` summary
  ("numeric value", matching `ceiln`/`roundn`/`truncn`), `cotd`/`tand`
  trailing periods, `cround` unused requires, `gammaincinv`
  argument-order notation, `lnf`/`round` `@returns`, `truncsd`/
  `binomcoef`/`fast/hypot`/`fast/hypotf` `@param` descriptions,
  `gamma-lanczos-sum-expg-scaled` unbalanced parenthesis, `sind` example
  spacing, `fast/maxf` stray blank line, and a few missing `@example`
  tags and interface doc comments.

This PR addresses the TypeScript declarations (plus the `kernel-betainc`
`lib` JSDoc); the generated namespace aggregator will pick up these
fixes on regeneration. Several findings that are errors replicated
across a package's other doc surfaces (`cscd`, `nonfibonaccif`,
`nonfibonacci`, `powf`) are handled package-wide in a separate PR.

---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
  - task: lint_filenames
    status: passed
  - task: lint_editorconfig
    status: passed
  - task: lint_markdown_pkg_readmes
    status: na
  - task: lint_markdown_docs
    status: na
  - task: lint_markdown
    status: na
  - task: lint_package_json
    status: na
  - task: lint_repl_help
    status: na
  - task: lint_javascript_src
    status: passed
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: na
  - task: lint_javascript_tests
    status: na
  - task: lint_javascript_benchmarks
    status: na
  - task: lint_python
    status: na
  - task: lint_r
    status: na
  - task: lint_c_src
    status: na
  - task: lint_c_examples
    status: na
  - task: lint_c_benchmarks
    status: na
  - task: lint_c_tests_fixtures
    status: na
  - task: lint_shell
    status: na
  - task: lint_typescript_declarations
    status: passed
  - task: lint_typescript_tests
    status: passed
  - task: lint_license_headers
    status: passed
---
@Planeshifter Planeshifter force-pushed the philipp/docs-fix-base-special-declarations branch from 796b024 to 395f690 Compare June 3, 2026 00:54
@Planeshifter Planeshifter changed the title docs: fix TSDoc issues across many @stdlib/math/base/special declarations docs: fix TSDoc issues across many math/base/special declarations Jun 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

Math Issue or pull request specific to math functionality.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@Planeshifter @stdlib-bot