jsdoc

name	jsdoc
description	How to write JSDoc on @rhinestone/sdk public symbols, which is autogenerated into the published SDK Reference. Use when adding or editing doc comments on entry points, the account instance, actions, or utils in sdk/src.
user-invocable	false

SDK JSDoc

JSDoc on the SDK's public surface is the source for the published SDK Reference on the docs site — it is generated, not hand-written. What you write in the doc comment ships verbatim to integrators, so it must be both present and high quality. A missing or lazy comment becomes a missing or lazy reference page.

The mechanics of running the generator and committing the output live in docs/codegen.md — use them; don't repeat them here. This skill is about writing the comment well.

Apply when

You are adding or editing JSDoc on a hot-path public symbol: an entry point, an account-instance method, an action, or a util. For account-instance methods, see Canonical location below.

What the generator does with your JSDoc

Each reference page is a fixed template filled from your doc comment. Write for the template — every part below maps to a rendered section.

In the doc comment	Renders as
First paragraph of the summary	the page description — the one-line lead, shown on its own. Must read standalone.
Remaining paragraphs	the extended explainer prose under the title
@param name desc	a row in the Parameters table (object-literal types expand into sub-fields)
@returns desc	the Returns section
@example	the Usage code block. Omit it and a snippet is synthesized from the signature — correct but lifeless.
@remarks	a <Note> callout
experimental_ prefix on the symbol	an experimental <Warning> (added automatically — don't write it by hand)
@see / {@link Symbol}	a See also entry, resolved by bare symbol name to its page

Canonical location

For methods on the account instance (the object returned by createAccount), the JSDoc that TypeDoc reads lives on the RhinestoneAccount interface member, not the inner implementation. Document the interface; the implementation needs no doc comment. Putting it on the implementation means it never reaches the reference.

Patterns

Lead with a standalone one-liner

The first sentence becomes the page description and is shown without the rest, so it must be a complete statement of what the symbol does — no trailing context required. Keep it consistent with sibling symbols (imperative verb or noun phrase).

// Good
/** Enable a smart session. */
/** Prepare a transaction for signing. */

// Avoid
/** This function is used to enable a session ... */   // filler
/** The session — see below for how it works. */       // fragment, leans on the next paragraph

Describe meaning in @param, not the type

The type already shows in the Parameters table. The description adds what the type can't: units, constraints, what a good value looks like, what happens when it's omitted.

// Good
/** @param session resolved session to enable */

// Avoid
/** @param session the session */   // restates the name, adds nothing

Author an @example when the call isn't self-evident

The synthesized snippet just lists arguments positionally. Author one whenever argument order, surrounding setup, or realistic values would help the reader. Keep it minimal and runnable-looking.

/**
 * Prepare a transaction for signing.
 *
 * Resolves token requests and routing, then returns the signable payload along
 * with the available settlement quotes. Inspect `quotes.all` before signing —
 * the chosen quote is what `signTransaction` commits to.
 *
 * @param input the transaction to prepare
 * @returns the prepared transaction, including `quotes.all`
 * @example
 * const prepared = await account.prepareTransaction({
 *   targetChain: base,
 *   calls: [...],
 *   tokenRequests: [{ address: 'USDC', amount }],
 * })
 * @see {@link signTransaction}
 */

Body prose for the "why", @remarks for a caveat

Use extended paragraphs to explain behavior an integrator must understand to use the symbol correctly — especially non-obvious constraints (e.g. why an argument must be pre-resolved, what an off-nominal input does). Reserve @remarks for a single side-note; it renders as a callout, so don't bury required information there.

Cross-reference by bare name

Link related symbols with {@link toSession} inline and @see for "you probably also want" pointers. The generator resolves the bare name to its page — only documented hot-path symbols resolve; anything else renders as plain inline code, so don't link types/errors/internal helpers expecting a link.

Non-goals

• Don't document internal-only symbols here — JSDoc is welcome, but this skill is about the published surface.
• Don't restate API design guidance (use the dx skill) or changelog wording (use the changesets skill).