docs: remove redundant @returns {void} from @stdlib/fs/open and @stdlib/fs/resolve-parent-paths

[Planeshifter]

Description

What is the purpose of this pull request?

This pull request:

• removes the @returns {void} JSDoc tag from the exported async function in two @stdlib/fs/* packages that diverged from the namespace convention. Of 16 packages in @stdlib/fs/*, 14 (87.5%) omit @returns on the exported callback-style async function; the two outliers carried @returns {void}, which adds no information when the callback is the result channel.

@stdlib/fs/open

Remove the @returns {void} line from the JSDoc block of the exported async open in lib/main.js, aligning it with the 87.5% of @stdlib/fs/* packages (14 of 16) that omit a @returns tag on the callback-style async function and matching siblings such as read-file, close, and append-file. The sync overload's @returns annotation in lib/sync.js is untouched.

@stdlib/fs/resolve-parent-paths

Drops the redundant @returns {void} tag from the async resolveParentPaths JSDoc in lib/main.js, aligning it with the 87.5% of @stdlib/fs/* packages that omit the tag on callback-style exports (e.g. read-file, close, append-file) where the callback is the result channel. The inner first/some/all/each helpers keep their @returns {void} tags, and lib/sync.js is untouched.

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.

Comment-only edit; no runtime behavior, public signature, type declaration, or test expectation changes. Two commits, one per outlier package.

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 PR was generated by an automated cross-package drift detection routine running on Claude Code: structural and semantic features were extracted from all 16 packages in @stdlib/fs/*, the majority pattern per feature was computed (≥75% threshold), outliers were validated by independent reviewer subagents, and the surviving mechanical corrections were applied. Final review is the maintainer's call.

---

@stdlib-js/reviewers

---

Generated by Claude Code

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
fs/open	$\\color{green}194/194$ $\\color{green}+100.00\\%$	$\\color{green}12/12$ $\\color{green}+100.00\\%$	$\\color{green}2/2$ $\\color{green}+100.00\\%$	$\\color{green}194/194$ $\\color{green}+100.00\\%$
fs/resolve-parent-paths	$\\color{green}786/786$ $\\color{green}+100.00\\%$	$\\color{green}112/112$ $\\color{green}+100.00\\%$	$\\color{green}21/21$ $\\color{green}+100.00\\%$	$\\color{green}786/786$ $\\color{green}+100.00\\%$

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

[Planeshifter]

Closing — Lint Changed Files flagged valid-jsdoc / Missing JSDoc @returns for function on the diff, which inverts the premise of this PR.

The drift detector measured presence/absence of @returns across the 16 packages in @stdlib/fs/* and found 14/16 = 87.5% of exported callback-style async functions omit the tag, treating the two packages that carry @returns {void} (fs/open, fs/resolve-parent-paths) as outliers. CI shows that the lint rule is the actual canon: @returns is required, and the 14 packages omitting it are pre-rule leftovers that lint never re-runs on (only changed files are linted). Removing the tag from the two compliant packages regresses them.

Reverted both commits and closing this PR. The local drift report has been updated to record the inverted direction so future runs can apply the right gate (cross-check candidate "missing-tag" majorities against the active ESLint config before flagging).

---

Generated by Claude Code