docs: align _tools/pkgs/* outliers with namespace JSDoc conventions

[Planeshifter]

Description

Aligning outliers in _tools/pkgs with namespace majority patterns (random namespace pick, seed 20260424).

Namespace summary

• Namespace: _tools/pkgs
• Members analyzed: 25 (0 excluded as autogenerated)
• Features analyzed: file tree, package.json shape, README section structure, test/benchmark/example/lib/docs/etc/bin file naming, public signature, return kind, validation prologue, error construction, JSDoc shape, @stdlib/* dependency set.
• Features with clear majority (≥75%): all top-level package.json keys (100%), directories.{doc,example,lib} (100%), docs/usage.txt (100%), etc/cli_opts.json (100%), bin/cli (100%), examples/index.js (100%), H2 Usage/CLI (100%) and Examples (96%), H3 Usage/Examples (100%) and Notes (92%), directories.test (96%), errorConstruction=format (100%), jsdocShape.hasExample=true (100%), returnKind=void (84%), JSDoc @returns present (88%), and the core @stdlib/assert/* + @stdlib/string/format + @stdlib/utils/copy dependency set (≥84%).
• Features without clear majority (excluded from drift detection): file tree as a whole (every package has package-specific lib/ helpers), lib/* file naming, scripts keys (empty across all members), JSDoc options paramTag hasDescription (13 true / 10 false — 52% — below threshold), H2 Notes (64%).

_tools/pkgs/addons

Adds a missing @returns {void} JSDoc tag to the primary function in _tools/pkgs/addons/lib/async.js, bringing it in line with 22 of the 25 non-autogenerated packages in the _tools/pkgs/ namespace (88% conformance). The tag is inserted between the last @throws and the @example block, matching the ordering convention used by sibling packages. Reviewers can verify placement against any of the conforming siblings in _tools/pkgs/.

_tools/pkgs/browser-deps

Fixes JSDoc drift in _tools/pkgs/browser-deps relative to the _tools/pkgs/ namespace. Added missing @returns {void} JSDoc tag to pkgDeps in lib/async.js, placing it between the last @throws and the @example block to match the 22/25 (88%) siblings that already carry the tag. Reviewers can confirm conformance by scanning the remaining _tools/pkgs/ members for the same pattern.

_tools/pkgs/deps

Fixes JSDoc drift in _tools/pkgs/deps relative to the _tools/pkgs/ namespace. Added missing @returns {void} JSDoc tag to pkgDeps in lib/async.js, placing it between the last @throws and the @example block to match the convention followed by 22 of 25 siblings (88% conformance). Reviewers can diff against any conforming peer (e.g., _tools/pkgs/entry-points or _tools/pkgs/browser-entry-points) to confirm alignment.

Validation

Checks performed:

• Structural feature extraction across all 25 members (file trees, package.json shape, README headings, test/benchmark/example/lib/docs/etc/bin file naming).
• Semantic feature extraction via per-package agents for each member (public signature, return kind, validation prologue, error construction, JSDoc shape, @stdlib/* dependency set).
• Three-agent drift validation: opus semantic-review for JSDoc outliers, opus cross-reference for downstream impact, sonnet structural-review for structural outliers.

Deliberately excluded:

• Features without a clear 75% majority (JSDoc options paramTag description, H2 Notes, file-tree as a whole, lib/* naming).
• installed outlier on directories.test in package.json — the package has no test/ directory on disk, so adding the field would advertise a non-existent path. Structural and cross-reference agents both flagged this as intentional-deviation / needs-human. Logged for follow-up.
• returnKind=value outliers (dep-list, name2bucket, name2standalone, namespace-deps) — these are genuinely synchronous pure-value functions; not drift.
• Any outlier requiring cascading changes to tests, examples, or public behavior.

Related Issues

None.

Questions

No.

Other

Produced by the drift-detection routine with seed 20260424. Full per-feature breakdown, the outlier list with drop reasons, and the list of namespaces surveyed during eligibility enumeration are saved in a local report outside the working tree.

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 produced by an automated cross-package drift-detection routine running under Claude Code. The routine picked the _tools/pkgs namespace at random (seed 20260424), extracted structural and semantic features from all 25 non-autogenerated members, identified the majority pattern for each feature, validated candidate corrections via three independent sub-agents (semantic-review, cross-reference, structural-review), and emitted purely mechanical JSDoc edits for the three outliers that survived filtering. No public behavior, tests, or signatures were modified.

---

---

Generated by Claude Code

[Planeshifter]

Reverting — drift finding was a false positive

The Lint Changed Files failure surfaced a deeper problem with this run's analysis. Re-counting @returns presence on the main-function JSDoc (not inner-callback JSDoc) across all 25 _tools/pkgs/* members gives:

• present on main function: 7/25 (28%)
• absent on main function: 18/25 (72%)

Neither side clears the 75% majority threshold, so there is no clear-majority drift for this feature. The original routine run reported 22/25 = 88% conformance because the per-package semantic-extraction agents conflated the primary function's JSDoc with inner-callback JSDocs (onResolve, onEntries, done, etc.) — the callbacks do uniformly carry @returns {void}, but the top-level functions do not.

The stdlib ESLint config also tells against the edit: valid-jsdoc runs with requireReturn: false and requireReturnDescription: true. Adding @returns {void} with no description to a function that doesn't return a value is exactly the shape the rule rejects — hence the CI failure.

Pushed three revert commits (one per outlier package) to restore the originals. The branch is now a no-op against develop; please close when convenient.

Filed under false-positive causes for future drift runs: the semantic-extraction agent prompt needs to pin analysis to the top-level function's JSDoc and explicitly ignore nested callback JSDocs.

---

Generated by Claude Code