ESLint for TSDoc

[michaelahern]

No description provided.

[amazon-q-developer]

This PR successfully adds ESLint support for TSDoc by integrating eslint-plugin-jsdoc and reformatting documentation comments to comply with TSDoc standards. The changes include proper configuration in ESLint, dependency updates, and documentation improvements throughout the codebase. All changes are working correctly with no defects identified that would block merge.

---

You can now have the agent implement changes and create commits directly on your pull request's source branch. Simply comment with /q followed by your request in natural language to ask the agent to make changes.

[Copilot]

Pull request overview

This PR adds ESLint-based validation for TSDoc/JSDoc comments in the TypeScript sources to improve documentation consistency, and updates existing docblocks to comply with the new rules.

Changes:

• Add eslint-plugin-jsdoc as a dev dependency and enable its flat/recommended-tsdoc config for *.ts files.
• Update WattBoxClient method docblocks to be more TSDoc-compliant (remove stray blank tag lines, add missing @returns, remove incorrect @param).
• Add an entry-point docblock to the example script.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/example.ts	Adds a top-level docblock describing required environment variables and program purpose.
src/client.ts	Adjusts TSDoc blocks across client methods (formatting, @returns, and tag cleanup).
eslint.config.js	Enables eslint-plugin-jsdoc’s flat recommended TSDoc rules for TypeScript files.
package.json	Adds eslint-plugin-jsdoc to devDependencies.
package-lock.json	Locks new transitive dependencies introduced by eslint-plugin-jsdoc.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 5 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (5)

src/client.ts:146

• The new @returns description doesn’t match the implementation: this method can return an empty string when the response doesn’t match. Consider documenting the empty-string fallback (or throwing/returning null instead) to avoid misleading API docs.

    /**
     * Get the hostname of the WattBox.
     * @remarks
     * Protocol Command: ?Hostname
     * @returns The hostname of the WattBox
     * @throws {@link WattBoxError}
     */
    public async getHostname(): Promise<string> {
        const response = await this.#handleRequestMessage('?Hostname');

src/client.ts:159

• The new @returns text says it returns a model number string, but the implementation falls back to '' if parsing fails. Please document the empty-string fallback (or adjust the implementation) so generated docs remain accurate.

    /**
     * Get the model number of the WattBox.
     * @remarks
     * Protocol Command: ?Model
     * @returns The model number string
     * @throws {@link WattBoxError}
     */
    public async getModel(): Promise<string> {
        const response = await this.#handleRequestMessage('?Model');

src/client.ts:172

• The new @returns text implies a real outlet count is always returned, but the implementation falls back to 0 if parsing fails. Please document that 0 may mean “unavailable/parse failure” (or change the behavior to throw/return null) so callers can interpret results correctly.

    /**
     * Get the number of outlets on the WattBox.
     * @remarks
     * Protocol Command: ?OutletCount
     * @returns The number of outlets
     * @throws {@link WattBoxError}
     */
    public async getOutletCount(): Promise<number> {
        const response = await this.#handleRequestMessage('?OutletCount');

src/client.ts:185

• The new @returns text doesn’t mention that this method can return an empty array when parsing fails. Please document that fallback (or adjust the behavior) to keep docs accurate for consumers.

    /**
     * Get the names of all outlets on the WattBox.
     * @remarks
     * Protocol Command: ?OutletName
     * @returns An array of outlet names
     * @throws {@link WattBoxError}
     */
    public async getOutletNames(): Promise<string[]> {
        const response = await this.#handleRequestMessage('?OutletName');

src/client.ts:263

• The new @returns description says a service tag string is returned, but the implementation can return '' if parsing fails. Please document the empty-string fallback (or change the behavior) so API docs align with runtime behavior.

    /**
     * Get the service tag of the WattBox.
     * @remarks
     * Protocol Command: ?ServiceTag
     * @returns The service tag string
     * @throws {@link WattBoxError}
     */
    public async getServiceTag(): Promise<string> {
        const response = await this.#handleRequestMessage('?ServiceTag');

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

eslint-plugin-jsdoc@62.9.0 (added here) requires Node ^20.19.0 || ^22.13.0 || >=24 per the lockfile, but this repo declares engines.node as >=22. This can break installs on Node 22.0–22.12; either bump the repo engine requirement (e.g., to >=22.13.0) or pin/choose a plugin version that supports the currently declared range.

[Copilot]

The new @returns description is incomplete vs the implementation: this method returns an empty string when the response doesn’t match, not always a firmware version. Update the @returns text (or behavior) so the docs reflect possible '' results.

Suggested change

	* @returns The firmware version string
	* @returns The firmware version string, or an empty string if the response does not match the expected format