JS and JSDoc #

JS modules (.js, .mjs, .jsx), JS components, and JS <script module> blocks document like their TS twins: svelte-docinfo reads their JSDoc the way TypeScript's checker does, so /** @param {string} a */ types a parameter as a: string would. allowJs is always on for the analysis, so no tsconfig change is needed, and checkJs isn't required.

TypeScript reads none of this in .ts files: there, JSDoc types and the tags below annotate nothing, as in your editor.

Types and parameters
#

A @type, @param, @returns, or @property type is the written annotation at its site, so it recovers alias names and keeps union order as written, like a TS annotation (see structured types).

/** * @param {string} a - a required parameter * @param {number} [b] - optional, as is `{number=}` * @param {number} [c=0] - optional, with defaultValue "0" * @param {object} [d] - an options object * @param {boolean} [d.e] - documents d's property e */ export function fn(a, b, c = 0, d) {}

@typedef and @callback
#

A @typedef or @callback documents as a type alias, like type A = …: @property tags become members with their descriptions, a callback gets a (call) member, and @template tags its generics. A const A with a same-named @typedef A documents as one declaration with mergedValue: true.

As in your editor's hover, a JSDoc block that declares a typedef and has no @param or @returns documents the typedef, not the declaration below it. Give the declaration its own block:

/** * A point. * @typedef {object} Point * @property {number} x - the horizontal position * @property {number} y - the vertical position */ /** The origin. */ export const ORIGIN = {x: 0, y: 0};

A @module block keeps its prose for the module, and a component's JSDoc above $props() for the component. A @typedef in a component's HTML @component comment documents nothing. Declare a component's props typedef in a block of its own, since svelte2tsx copies the block above $props() into its generated code, where svelte-check reports a typedef as a duplicate.

An @enum const documents as kind: 'enum', one member per property.

@template
#

@template tags are genericParams on functions, classes, and methods, with constraints (@template {string} K) and defaults (@template [K='k']), as <K extends string = 'k'> writes them.

@overload
#

Each @overload tag declares a signature, documented by the block it sits in and the @param and @returns tags after it. The first overload documents the function, and the implementation's own block is hidden, as in a TS overload set, so put the prose and tags like @example on the first overload; a documented implementation warns implementation_doc_hidden. Write @template before @overload, since TypeScript rejects one between @overload and its @params.

/** * Doubles a number or a bigint. * @overload * @param {number} n - the number to double * @returns {number} * @example double(2) // 4 */ /** * @overload * @param {bigint} n - the bigint to double * @returns {bigint} */ /** @param {number | bigint} n */ export function double(n) { return /** @type {any} */ (n) * 2; }

Classes
#

  • @private hides a member, and @protected, @public, and @readonly add modifiers, like the TS keywords.
  • @implements {A} fills implements, and @extends {Base<T>} beside extends Base gives the type arguments.
  • this.x = … in the constructor, a method, or an accessor declares a member (static in a static method or block), typed by its first @type and documented by its first documented assignment, preferring the constructor's. These members list just before the constructor, where a TS class declares its fields.
  • A name the base class declares stays the base's (this.name = … in an Error subclass lists nothing). To document it on the subclass, write a field.

Components
#

A JS component's props come from the JSDoc @type on $props(), often a typedef, else from the destructuring. A legacy component's export let props read their @type and initializer.

<script> /** * @typedef {object} Props * @property {string} a - documents prop a */ /** * The component's docs. * @type {Props} */ const {a} = $props(); </script>

CommonJS
#

CommonJS isn't modeled. A JS file with no import or export that exports through module.exports or exports.x documents nothing and warns commonjs_unsupported. Under node16/nodenext or moduleDetection: 'force', TypeScript reads CommonJS exports itself, so named ones (exports.x, module.exports = {a, b}) document. Exports defined through Object.defineProperty or a UMD wrapper document nothing, with no warning.

Limits
#

  • Assignments outside a class (A.prototype.x = …, A.x = …) don't add class members.
  • An @overload's rest parameter ({...T}) is rest, but types as T | undefined, as TypeScript reads it.
  • A @property after a non-@property tag leaves the typedef's property list, as TypeScript reads it, and is dropped.