docs: fix JSDoc annotations

[Planeshifter]

Description

What is the purpose of this pull request?

This pull request corrects JSDoc annotations in three @stdlib/_tools/pkgs packages whose public documentation disagrees with their own runtime behavior and with the documented conventions of their sibling packages. All changes are comment-only; no runtime code, signature, or test expectation is touched.

The three packages were identified by extracting structural and semantic features from all 25 members of the @stdlib/_tools/pkgs namespace and flagging packages deviating from a pattern shared by at least 75% of members.

Namespace summary

• Members analyzed: 25 (all direct children of lib/node_modules/@stdlib/_tools/pkgs containing a package.json; none are autogenerated).

• Features analyzed: 14 — file tree, package.json top-level keys, scripts keys, stdlib keys, manifest.json keys, README section set, README section order, test//benchmark//examples/ filenames, public signature, validation prologue, error construction, JSDoc @param/@throws/@returns shape, @example presence, and require() dependencies.

• Features with a clear majority (≥19/25): 9. Four of them had outliers:

  Feature	Conformance	Outliers
  @param {Options} [options] bracketed when options is optional	22/25 (88%); 22/23 (96%) of packages taking an options argument	installed
  @throws {TypeError} options argument must be an object	21/25 (84%); 21/23 (91%) of packages with lib/validate.js	dep-list, namespace-deps
  @throws {TypeError} must provide valid options	21/25 (84%); 21/23 (91%)	dep-list, namespace-deps
  public option @param type agrees with the same package's lib/validate.js	22/25 (88%); 22/23 (96%)	namespace-deps

  The remaining five majority features (package.json key set, examples/ filenames, @example presence, errorConstruction = format, empty scripts) were fully conformant across all 25 members.

• Features without a clear majority, excluded from analysis: 5 — README ## Notes section presence (16/25, 64%), full README section order (16/25, 64%), presence of lib/sync.js (15/25, 60%), lib/async.js (15/25, 60%), and options.pattern glob validation (15/25, 60%).

@stdlib/_tools/pkgs/dep-list

Adds @throws {TypeError} options argument must be an object and @throws {TypeError} must provide valid options to the public JSDoc of depList. depList passes opts and options to validate and re-throws the returned error; lib/validate.js returns a TypeError for a non-object options argument and for an invalid dev or manifest option, and test/test.js asserts both throw paths. The annotations match 21 of the 23 namespace siblings that have a lib/validate.js (91%), or 84% of all 25 namespace members; dep-list was one of two packages without them.

@stdlib/_tools/pkgs/namespace-deps

Corrects the JSDoc in lib/main.js to match lib/validate.js. The options.dev type changes from {string} to {boolean}, and the options.level type changes from {number} to {PositiveInteger}. Also adds @throws {TypeError} annotations for options argument must be an object and must provide valid options, which namespaceDeps re-throws from validate() and which test/test.js and test/test.validate.js already assert. The @param types now agree with lib/validate.js in the same way as 22 of 23 sibling packages (96%), and the @throws annotations match 21 of 23 siblings that have a lib/validate.js (91%).

@stdlib/_tools/pkgs/installed

Marks the options parameter of pkgs as optional, changing @param {Options} options to @param {Options} [options]. pkgs dispatches on arguments.length and treats a single argument as the callback, and the README documents the signature as pkgs( [options], clbk ). Both the README's first example and examples/index.js call pkgs( onPkgs ), and the child annotations ([options.dir], [options.depth], [options.dev=true]) were already bracketed. installed was the only public outlier; 22 of 23 siblings taking an options argument bracket it (96%), or 88% of all members.

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: 3 files, +7/−3 lines, all inside JSDoc comment blocks.

Validation

What was checked:

• Structural extraction over all 25 members: file trees, package.json/manifest.json key sets, README heading sequences, and test//benchmark//examples/ filenames.
• Semantic extraction per package (public signature, validation prologue, error construction, JSDoc shape, require() dependencies), then re-derived directly from source. The per-package extraction initially mis-reported @param bracketing for several packages; every finding in this pull request was re-verified against the source text before being acted on, and the conformance counts above come from that re-derivation, not from the extraction pass.
• Three-pass review of each candidate: semantic review (is the deviation justified by a genuine behavioral difference?), cross-reference review (do tests, examples, or a documented contract depend on the deviation?), and structural review (is the majority pattern the right thing to apply, and where does each tag belong?). All three passes confirmed all three corrections.
• Lint rule compatibility, by hand: jsdoc-tag-order orders param < throws < returns, so the inserted @throws lines are correctly positioned; jsdoc-no-duplicate-tags lists throws among its exceptions, so multiple @throws tags are permitted; PositiveInteger is in the jsdoc-typedef-typos allowlist.
• Generated artifacts: none of the three packages has a *.d.ts, docs/types/, or docs/repl.txt, so no generated file now disagrees with the JSDoc. docs/usage.txt is CLI-only and untouched.
• Syntax: node --check passes on all three modified files.

node_modules is not installed in the environment where these changes were prepared, so ESLint and the tape test suites were not run locally; CI will be the first execution of either. The changes are confined to comment text, so no test expectation changes.

What was deliberately excluded:

• find — missing options.pattern validation and its @throws {Error} annotation. 15 of the 16 packages exposing an options.pattern option reject a pattern not ending in package.json; find does not. Adding the check would change observable behavior, and adding only the annotation would document an error that is never thrown. Left for a maintainer to decide.
• installed — no test/ directory (and correspondingly no "test" entry in directories). Writing a test suite is out of scope, and adding the directories entry alone would point at a directory that does not exist.
• dep-list, installed, name2bucket, name2standalone, namespace-deps — no lib/sync.js. Adding a synchronous API changes the public API surface. The feature also lacks a clear majority (15/25, 60%).
• dep-list, namespace-deps — no ### Notes section under ## CLI. Present in 23/25 READMEs, but sibling content is package-specific prose, not mechanically derivable.
• Features without a clear majority, listed above, were excluded rather than resolved by plurality.

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. Example disclosures: "This PR was written primarily by Claude Code." or "I consulted ChatGPT to understand the codebase, but the proposed changes were fully authored manually by myself.".

This pull request was written primarily by Claude Code. It ran an automated cross-package consistency audit over the @stdlib/_tools/pkgs namespace: feature extraction was partly performed by subagents, the resulting findings were re-derived from source and verified by three independent review passes, and the final edits, commit messages, and this description were authored by Claude Code. Reviewers should note in particular that the conformance percentages quoted above were computed programmatically from the working tree, and that ESLint and the test suites were not run locally (see Validation).

---

@stdlib-js/reviewers

🤖 Generated with Claude Code

https://claude.ai/code/session_014UdGBAZUyqVKsGZygrZaJk

---

Generated by Claude Code