Skip to content

docs: fix JSDoc descriptions copied from other methods - #592

Merged
koral-- merged 3 commits into
masterfrom
docs/fix-jsdoc-copy-paste
Nov 20, 2026
Merged

koral-- merged 3 commits into
masterfrom
docs/fix-jsdoc-copy-paste

Conversation

@koral--

@koral-- koral-- commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

Supersedes #545

Thanks @ttmx for spotting that the JSDoc on DeviceClient.reboot() described root(). This PR fixes that one and others of the same kind (a description copied from another method, a wrong parameter, a stale signature) that turned up when I compared the public JSDoc in src/ with the README API sections.

reboot()

  • The first sentence is rewritten to match the README's device.reboot([target]) section: it reboots, optionally into a target mode, and resolves when adbd closes the connection as the device goes down, not once the device is back.
  • @return true is now @returns true, like the neighbouring remount(), clear(), usb() and forward().
  • The @param target text is unchanged.

Other mismatches fixed

Where Problem Fix
getFeatures() JSDoc Documented a flags parameter (pm list packages filters). The method takes no arguments; the doc belongs to getPackages(). Removed.
getPackages(flags) JSDoc @param flags TODO, and @returns described device features. Moved the flags doc here; @returns An array of package names.
listReverses() JSDoc "Lists forwarded connections", copied from listForwards(). "Lists reversed connections".
startService() JSDoc @param options The activity configuration., copied from startActivity(). "The service configuration." (as in the README).
screencap() JSDoc Fallback named as client.framebuffer(serial, 'png'), the 2.x signature. DeviceClient.framebuffer() takes only the format. client.framebuffer('png').
StartServiceOptions.user "Not set by default". That holds for startActivity(), which shares the interface, but startService() defaults it to 0 (code and README). States both defaults.
README device.getFeatures() / device.getPackages() Same flags mix-up as the JSDoc. Moved the flags to device.getPackages([flags]).
README device.listReverses() Same "forwarded connections" line. "reversed connections".
README device.screencap() Same 2.x framebuffer(serial, 'png'). framebuffer('png').

Left alone on purpose

  • Style-only differences:
    • @return vs @returns on root() and screencap()
    • typos such as "Attemps" and "connextion"
    • the truncated "The stream also has a meta.:" in framebuffer()'s @returns
  • The README's many callback(err, …) bullets for methods that no longer take callbacks. That's a README-wide cleanup and out of scope here. The JSDoc doesn't mention callbacks except where they are still supported (util.readAll, sync.stat, …).
  • client.ts, sync.ts and the transfers have no JSDoc on their public methods, so there was nothing to compare there.

Review follow-ups

  • startService() retried forever when the device rejected --user: the retry set options.user to undefined, and the default put --user 0 straight back. It now sets null, which the default leaves alone, and StartServiceOptions.user accepts null (also documented as a way to leave --user out). This is the one code change in this PR. A new test makes the device reject --user once and checks that the second request has no --user; with the old undefined it fails.
  • reboot(): RebootCommand waits for adbd to close the connection, so the JSDoc and README now say it resolves then, not when ADB accepts the command.
  • getPackages(flags): the docs now say the string goes to the device shell unescaped. Not escaped in code, because one string carries several flags ('-3 -f').
  • device.*, not client.*, for the DeviceClient methods the docs pointed at: framebuffer() (screencap fallback), isInstalled(), push(), and stat()/push()/pull() in syncService(). The 2.x changelog line about client.framebuffer() stays as history.
  • README device.listReverses(): the callback is callback(err, reverses).

npm run lint, npm run compile and npm test pass.

🤖 Generated with Claude Code

koral-- and others added 2 commits November 20, 2026 17:25
- reboot(): described root(). Describe the reboot and use @returns.
- getFeatures() documented a flags parameter it doesn't take; it belongs
  to getPackages(), whose own @PARAM was a TODO and whose @returns
  described features instead of package names.
- listReverses() said it lists forwarded connections.
- startService() called its options the activity configuration.
- screencap() pointed at the 2.x framebuffer(serial, 'png') signature.

Thanks to @ttmx for spotting the reboot() one in #545.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Karol Wrótniak <karol.wrotniak@droidsonroids.pl>
- StartServiceOptions.user said "not set by default", which is true for
  startActivity() only: startService() defaults it to 0, as the README
  says.
- The README had the getFeatures()/getPackages() flags mix-up and the
  listReverses() "forwarded connections" line too, and the 2.x
  framebuffer(serial, 'png') signature under screencap().

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Karol Wrótniak <karol.wrotniak@droidsonroids.pl>
@koral-- koral-- closed this Nov 20, 2026
@koral-- koral-- reopened this Nov 20, 2026
When the device rejected --user, startService() cleared the option to
undefined and called itself, which put --user 0 straight back, so it
retried forever. Clear it to null, which the default leaves alone, and
allow null in StartServiceOptions.user.

Also from review: say that reboot() resolves when adbd closes the
connection, that getPackages() flags go to the device shell unescaped,
name the listReverses() callback value reverses, and point at device.*
for the DeviceClient methods the docs called client.*.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Karol Wrótniak <karol.wrotniak@droidsonroids.pl>
@koral--
koral-- merged commit 9deaf00 into master Nov 20, 2026
6 checks passed
@koral--
koral-- deleted the docs/fix-jsdoc-copy-paste branch November 20, 2026 18:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant