docs: add missing @returns tag to main function JSDoc across _tools/github outliers

[Planeshifter]

Description

Adds the missing * @returns {void} JSDoc tag to the public main function in four @stdlib/_tools/github packages. Nineteen of twenty-three sibling packages in the namespace (83%) already carry this tag on the main function; this brings the four outliers into conformance with no behavior change.

Namespace summary

• Namespace: @stdlib/_tools/github
• Members analyzed: 23 (0 autogenerated, 23 hand-authored)
• Structural features extracted: file tree, package.json top-level keys, scripts, stdlib keys, README section list, manifest.json keys, test/ benchmark/ examples/ file naming
• Semantic features extracted (per-package agent reads of lib/main.js, lib/index.js, lib/validate.js): public signature, validation prologue, error-construction kind, JSDoc shape, dependencies
• Features with a clear majority (≥75% conformance): package.json top-level key set (100%), scripts shape (100% empty), manifest.json absence (100%), error-construction kind (100% format), core file set — README.md, bin/cli, docs/usage.txt, etc/cli_opts.json, examples/index.js, lib/index.js, lib/main.js, package.json (100%), lib/validate.js (96%), lib/defaults.json (91%), test/test.{cli,main,js,validate}.js (87–91%), README ## Usage / ## Examples / ## CLI (100%), @returns {void} on main function JSDoc (83%)
• Features without clear majority (excluded from drift analysis): @example presence in main JSDoc (26%), @throws presence in main JSDoc (30%), lib/factory.js presence (74%), ## Notes README heading (78%, borderline — flagged but not corrected because adding notes requires package-specific content)
• Outliers whose deviation reflects systematic underdevelopment (excluded as out-of-scope cascading work): dependents and dependents-count (no test/ directory at all); fetch-file (missing lib/validate.js and several test fixtures); user-rate-limit (missing test/fixtures/info.json, but its existing tests do not reference the fixture)

Per-outlier corrections

_tools/github/create-issue

Public createIssue( slug, title, options, clbk ) is a callback-style async function with no synchronous return value. The JSDoc block listed five @throws tags and an @example but no @returns. Added * @returns {void} between the last @throws and the blank * line preceding @example, matching the position used in sibling packages (e.g. create-repo, create-token, dispatch-workflow post-fix).

_tools/github/dependents

Public dependents( slug, options, clbk ) is a callback-style async function that delegates to resolve( opts, done ). The inner done callback was already annotated @returns {void}; the outer function was not. Added * @returns {void} to the outer JSDoc block. README's "Returns the list of dependents …" is prose describing callback delivery, not a synchronous return value.

_tools/github/dependents-count

Same shape as dependents: public dependentsCount( slug, options, clbk ) is callback-style, terminates with resolve( opts, done ), and the inner done callback already carries @returns {void} while the outer function did not. Added * @returns {void} to the outer JSDoc block. README's "Returns the number of dependents …" is prose describing callback delivery.

_tools/github/dispatch-workflow

Public dispatch( slug, id, options, clbk ) is a callback-style async function structurally identical to create-issue and create-repo. The JSDoc listed five @throws and an @example but no @returns. Added * @returns {void} between the last @throws and the blank * line preceding @example.

Related Issues

No.

Questions

No.

Other

Validation

• Structural extraction over the 23-member namespace produced file-tree, package.json shape, README section, manifest, and test/ / benchmark/ / examples/ file inventories per package.
• Semantic extraction recorded JSDoc shape per package; the @returns tag on the public main function is present in 19 packages (create-repo, create-token, delete-token, fetch-file, followers, following, get, org-repos, rank-followers, rank-users, set-topics, star-repo, starred, subscriptions, user-details, user-orgs, user-rate-limit, user-repos, workflow-runs) and absent in the four outliers fixed here.
• Two independent validation agents confirmed the drift: a semantic-review pass verified each outlier is shape-identical to the conforming siblings (callback-style, no synchronous return); a cross-reference pass verified no test or example in any outlier package assigns the function's return value (var x = createIssue(...)-style invocations do not exist), no docs/types/index.d.ts declarations contradict {void}, and READMEs describe callback delivery rather than synchronous returns.
• Open-PR collision check via the GitHub MCP confirmed no in-flight PR proposes the same JSDoc fix. PR docs: propagate fixes across _tools and blas/base/ndarray siblings #12287 touches _tools/github/create-issue and _tools/github/dispatch-workflow for a @throws {TypeError} → @throws {Error} annotation in lib/validate.js only; no overlap with lib/main.js JSDoc.

Deliberately excluded

• ## Notes README heading drift (5 outliers) — adding a Notes section requires package-specific prose; not a mechanical fix.
• Missing lib/validate.js in fetch-file — would require domain-specific validation logic; not mechanical.
• Missing test/ directory in dependents and dependents-count — adding test files requires real test logic, not boilerplate; cascading scope.
• Missing test/fixtures/info.json in user-rate-limit — its existing tests do not reference this fixture, so adding it would be dead code.
• lib/defaults.json and test/fixtures/opts.js content drift — these files vary per package by design (different useragent, pathname, method, option shapes); not a single canonical pattern to normalize toward.

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 the automated cross-package drift detection routine. Per-package structural and semantic feature extraction, majority-vote drift identification, and two independent validation agents (semantic review and cross-reference) confirmed each outlier before the patch was applied. A maintainer should review classification and contents before promoting this draft.

---

@stdlib-js/reviewers

---

Generated by Claude Code