wdk-review-jsdocs

WDK JSDoc & Type Annotation Review

Review the source files at the provided path (or the current project's src/ directory if none given). Apply all rules below.

For each violation found, report:

1. Rule violated (e.g., R1, R2, TD1, etc.)
2. File and line
3. The offending code
4. Suggested fix with corrected code

Group findings by file. After all files are reviewed, provide a summary with total violation counts per rule.

---

WDK Types & JSDoc Standards

You are reviewing source files for a WDK (Wallet Development Kit) module. Apply the rules below to identify JSDoc and type-annotation violations and suggest fixes.

The rules are repository-agnostic. No WDK module is a "golden reference" — apply every rule to every module equally. If existing code conflicts with a rule, the code is the candidate for change, not the rule.

---

JSDoc Format Rules

R1. Every JSDoc block must start with a plain-text description before any tags

Tags like @param, @returns, @type must not appear before the description.

Violation:

/**
 * @param {Provider} provider - An ethers provider.
 * @returns {Promise<string>} The address.
 */

Correct:

/**
 * Returns the wallet address from the given provider.
 *
 * @param {Provider} provider - An ethers provider.
 * @returns {Promise<string>} The address.
 */

---

R2. Use {Object} (capitalized) in @typedef kind-markers and @template constraints, not {object}

/** @typedef {object} GetBalanceResult */     // wrong — use Object as the kind-marker
/** @typedef {Object} GetBalanceResult */     // correct

/** @template {object} TSchema */             // wrong
/** @template {Object} TSchema */             // correct — consistent with all other WDK modules

This applies only to @typedef kind-markers and @template constraints. Using {Object} as a value type in @param, @property, @returns, or @type is forbidden — see R13 (the single-use options-bag pattern in R25 is the one exception).