Skip to content

docs: correct documentation wording in three blas/base/wasm packages - #14363

Draft
Planeshifter wants to merge 3 commits into
developfrom
claude/busy-mayer-pux5p0
Draft

docs: correct documentation wording in three blas/base/wasm packages#14363
Planeshifter wants to merge 3 commits into
developfrom
claude/busy-mayer-pux5p0

Conversation

@Planeshifter

Copy link
Copy Markdown
Member

Description

What is the purpose of this pull request?

This pull request corrects three documentation-drift findings in the blas/base/wasm namespace, bringing three outlier packages back in line with the documentation conventions used by the rest of the namespace. All changes are documentation-only; no source behavior, public signatures, or test expectations are affected.

Namespace summary

  • Members analyzed: 33 non-autogenerated packages under @stdlib/blas/base/wasm.
  • Structural features (all with a clear majority, ≥75%): file tree, package.json key set / scripts / stdlib config, manifest.json key set, README section list and ordering, and test/ / benchmark/ / examples/ file naming were byte-uniform across all 33 packages.
  • Semantic features with a clear majority: main.js JSDoc shape (all packages document main, ndarray, and Module with examples), return kind (all export a Routine), and error construction (100% use format — a single, identical TypeError guard on the WebAssembly memory instance).
  • Features excluded for having no clear majority: public signature and require dependency sets, which legitimately vary per BLAS routine (single vs. double precision, real vs. complex, presence of a scalar argument, number of stride/offset arguments). These are correct-by-design differences, not drift.

Only three deviations from the namespace majority survived validation, all in package documentation:

blas/base/wasm/scasum

The lib/main.js JSDoc summary read "WebAssembly module compute the sum of the absolute values...", dropping the word "to". 32 of 33 packages (97%) use the form "WebAssembly module to ...", and scasum's own lib/index.js summary already reads "WebAssembly routine to compute...". Inserted the missing "to" to restore the sibling pattern; the described operation is unchanged.

blas/base/wasm/dswap

The README described the operation on "double-precision floating point vectors" (unhyphenated) in all five occurrences. The hyphenated compound modifier "floating-point" is used in 12 of the 14 sibling READMEs that mention the term, and in dswap's own lib/main.js JSDoc. Hyphenated all five occurrences to match; dswap and sswap were the only two READMEs in the namespace using the unhyphenated form.

blas/base/wasm/sswap

Identical to dswap: the README used "single-precision floating point vectors" (unhyphenated) in all five occurrences, contradicting the namespace majority and sswap's own lib/main.js JSDoc. Hyphenated all five occurrences to "floating-point".

Related Issues

Does this pull request have any related issues?

None.

Questions

Any questions for reviewers of this pull request?

The same unhyphenated "floating point" wording also appears in docs/repl.txt and docs/types/index.d.ts for dswap and sswap. Those files were intentionally left untouched here (declaration files are part of the public API and REPL fixtures are treated as generator-adjacent); a maintainer may prefer to normalize them in a follow-up.

Other

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

Validation. Structural features were extracted deterministically across all 33 packages. Semantic features were cross-checked both deterministically (error-construction, JSDoc tag structure, require sets, copyright headers) and via parallel review across three lenses (documentation, source/validation, metadata). Each surviving outlier was then independently reviewed by three validators — semantic review (intentional vs. unintentional drift), cross-reference (whether any test or example relies on the wording, and whether a documented API contract would break), and structural review (whether the majority form is what should actually be applied). All three validators returned confirmed-drift for all three outliers.

Deliberately excluded: per-routine signature and dependency differences (correct-by-design, no clear majority); the docs/repl.txt and docs/types/index.d.ts occurrences of the same hyphenation (out of scope per the above); and copyright-year differences across packages (these reflect authoring date, not drift). The structural analysis found no missing files or fields to add — the namespace is otherwise uniform.

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 indicating how you used AI assistance.

This PR was produced by Claude Code running an automated cross-package documentation-drift detection routine over the blas/base/wasm namespace. Claude performed the structural and semantic feature extraction, computed per-feature majority patterns, identified and validated the outliers, applied the documentation fixes, and drafted this description. All changes are documentation-only and were reviewed for behavior preservation.


Generated by Claude Code

claude added 3 commits August 18, 2026 00:27
The `lib/main.js` JSDoc summary was missing the word "to"
("WebAssembly module compute ..."), diverging from the sibling
convention "WebAssembly module to <verb> ..." present in 32 of 33
namespace packages (97% conformance) and from the package's own
`lib/index.js` summary. Insert "to" to restore the pattern. The
change is a grammar fix to a documentation comment and does not alter
the described operation or any public behavior.
The README referred to "double-precision floating point vectors"
(unhyphenated) in all five occurrences, diverging from the hyphenated
compound modifier "floating-point" used in 12 of 14 sibling READMEs
that mention the term and in the package's own `lib/main.js` JSDoc.
Hyphenate all occurrences to match the namespace convention. The
change is documentation-only and does not affect public behavior. The
same wording in `docs/repl.txt` and `docs/types/index.d.ts` is left
untouched, as those files are out of scope for this change.
The README referred to "single-precision floating point vectors"
(unhyphenated) in all five occurrences, diverging from the hyphenated
compound modifier "floating-point" used in 12 of 14 sibling READMEs
that mention the term and in the package's own `lib/main.js` JSDoc.
Hyphenate all occurrences to match the namespace convention. The
change is documentation-only and does not affect public behavior. The
same wording in `docs/repl.txt` and `docs/types/index.d.ts` is left
untouched, as those files are out of scope for this change.
@stdlib-bot stdlib-bot added the BLAS Issue or pull request related to Basic Linear Algebra Subprograms (BLAS). label Aug 18, 2026
@stdlib-bot

Copy link
Copy Markdown
Contributor

Coverage Report

Package Statements Branches Functions Lines
blas/base/wasm/dswap $\\color{green}661/661$
$\\color{green}+100.00\\%$
$\\color{green}17/17$
$\\color{green}+100.00\\%$
$\\color{green}6/6$
$\\color{green}+100.00\\%$
$\\color{green}661/661$
$\\color{green}+100.00\\%$
blas/base/wasm/scasum $\\color{green}553/553$
$\\color{green}+100.00\\%$
$\\color{green}17/17$
$\\color{green}+100.00\\%$
$\\color{green}6/6$
$\\color{green}+100.00\\%$
$\\color{green}553/553$
$\\color{green}+100.00\\%$
blas/base/wasm/sswap $\\color{green}661/661$
$\\color{green}+100.00\\%$
$\\color{green}17/17$
$\\color{green}+100.00\\%$
$\\color{green}6/6$
$\\color{green}+100.00\\%$
$\\color{green}661/661$
$\\color{green}+100.00\\%$

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

BLAS Issue or pull request related to Basic Linear Algebra Subprograms (BLAS).

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants