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 #
@privatehides a member, and@protected,@public, and@readonlyaddmodifiers, like the TS keywords.@implements {A}fillsimplements, and@extends {Base<T>}besideextends Basegives 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@typeand 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 anErrorsubclass 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}) isrest, but types asT | undefined, as TypeScript reads it. - A
@propertyafter a non-@propertytag leaves the typedef's property list, as TypeScript reads it, and is dropped.