JS with Types Start

Reference

JSDoc tags for TypeScript

A JSDoc tag is an @ word inside a /** */ comment. TypeScript reads a set of them as type annotations, so in a checked .js file @type, @param and their relatives do the work that : Type does in a .ts file.

Each page gives the syntax next to its TypeScript spelling, says whether TypeScript checks the tag, treats it as documentation or does not act on it, and runs every example through tsc when the site is built. The tags are listed in those three groups.

Checked by TypeScript

Tags TypeScript reads as types: in a checked .js file they do what annotations do in a .ts file, and a mismatch is an error.

  • @type

    The JSDoc @type tag gives a variable, property or expression a type that TypeScript checks: the syntax, casts with parentheses, and whole function types.

    • Checked by TypeScript

  • @param

    The JSDoc @param tag types a function parameter for TypeScript: optional and default values, rest parameters, options objects, and the errors it catches.

    • Checked by TypeScript
    • Alias @arg
    • Alias @argument

  • @returns

    The JSDoc @returns tag declares a function's return type, and TypeScript checks every return against it. Async functions, void, and when to leave it out.

    • Checked by TypeScript
    • Alias @return

  • @typedef

    The JSDoc @typedef tag names a reusable type: an object type built from @property lines, a union or anything else. Every @typedef in a module is exported.

    • Checked by TypeScript

  • @property

    The JSDoc @property tag lists the properties of a @typedef object type: optional ones in brackets, nested ones with dots. It is not read in a class comment.

    • Checked by TypeScript
    • Alias @prop

  • @callback

    The JSDoc @callback tag names a function type, built from @param and @returns lines, that you can use like any type. Syntax, generics and checked examples.

    • Checked by TypeScript

  • @template

    The JSDoc @template tag declares type parameters for generic functions, classes and typedefs, with constraints and defaults. Syntax and checked examples.

    • Checked by TypeScript

  • @satisfies

    The JSDoc @satisfies tag (TypeScript 5.0 and later) checks a value against a type but keeps the value's own, narrower type. When to use it instead of @type.

    • Checked by TypeScript

  • @import

    The JSDoc @import tag (TypeScript 5.5 and later) brings types from another module into a .js file with ES import syntax and nothing imported at run time.

    • Checked by TypeScript

  • @overload

    The JSDoc @overload tag (TypeScript 5.0 and later) gives a JavaScript function several call signatures, each with its own @param and @returns.

    • Checked by TypeScript

  • @this

    The JSDoc @this tag gives this a type inside a function, such as an event handler, and makes TypeScript check every call for that this. Syntax and examples.

    • Checked by TypeScript

  • @enum

    The JSDoc @enum tag types an object whose members share one type. How TypeScript reads it, why it is not a TypeScript enum, and a const object instead.

    • Checked by TypeScript

  • @class and @constructor

    @class and @constructor mark a JavaScript function as a constructor, so TypeScript requires new and types this. When you need them, and when a class is simpler.

    • Checked by TypeScript
    • Alias @constructor

  • @implements

    The JSDoc @implements tag makes TypeScript check that a JavaScript class has every member of a type, as implements does in a .ts file. Syntax and examples.

    • Checked by TypeScript

  • @extends and @augments

    @extends (or @augments) gives a JavaScript class's generic base its type arguments: @extends {Map<string, number>} with extends Map. Syntax and examples.

    • Checked by TypeScript
    • Alias @augments

  • @public

    The JSDoc @public tag marks a class member as usable from anywhere, which is already the default. When writing it helps, and the one place it is an error.

    • Checked by TypeScript

  • @private

    The JSDoc @private tag makes TypeScript reject uses of a class member outside the class. How it differs from a #private field, and where it misfires.

    • Checked by TypeScript

  • @protected

    The JSDoc @protected tag limits a class member to the class and its subclasses; TypeScript reports any use from outside them. Syntax and examples.

    • Checked by TypeScript

  • @readonly

    The JSDoc @readonly tag lets a class property be set only while the object is built. Where it works, why it breaks a @typedef, and what to write instead.

    • Checked by TypeScript

  • @override

    The JSDoc @override tag marks a method that replaces one in the base class. TypeScript checks the base has it, and noImplicitOverride makes the tag required.

    • Checked by TypeScript

Documentation

Tags for readers. Editors show them in hovers, and some get links or a strike-through, but none of them changes what tsc reports.

  • @deprecated

    The JSDoc @deprecated tag makes editors strike through a function, method or property and say what to use instead. tsc itself still passes the code.

    • Documentation only

  • @see

    The JSDoc @see tag points readers to a related function, class or web page. Since TypeScript 4.1 editors can go to the name it mentions; nothing is checked.

    • Documentation only

  • {@link}

    The inline {@link} tag turns a name in a JSDoc comment into a link editors can follow. Since TypeScript 4.3 hovers and go to definition work on it.

    • Documentation only
    • Alias @linkcode
    • Alias @linkplain

  • @example

    The JSDoc @example tag shows sample code in editor hovers, formatted as code in VS Code. TypeScript never checks that code, so an example can drift out of date.

    • Documentation only

  • @description and @summary

    In TypeScript the text before the first tag is the description; @description and @summary are shown as extra tags in hovers. Neither one is checked.

    • Documentation only
    • Alias @desc

  • @throws

    The JSDoc @throws tag documents the errors a function can throw. TypeScript links its type in editors but checks nothing, and a caught error is still unknown.

    • Documentation only
    • Alias @exception

  • @author, @since, @version and @todo

    @author, @since, @version and @todo are notes for readers. TypeScript shows them in hovers and checks nothing; write an email inside angle brackets.

    • Documentation only

Not checked by TypeScript

Tags from the JSDoc documentation tool that TypeScript does not act on. Each page shows what happens instead and what to write so the checker sees it.

  • @yields

    TypeScript does not support the JSDoc @yields tag. Type a generator with @returns {Generator<T>} instead, and TypeScript checks every yield against T.

    • Not checked by TypeScript
    • Alias @yield

  • @async

    The JSDoc @async tag does not make TypeScript treat a function as async. The async keyword does, and @returns {Promise<T>} gives the resolved type.

    • Not checked by TypeScript

  • @static

    TypeScript does not read the JSDoc @static tag, so a tagged method is still an instance method. Use the static keyword, or assign the function to the class.

    • Not checked by TypeScript

  • @const and @constant

    TypeScript ignores the JSDoc @const and @constant tags: a tagged let can still be reassigned. Use the const keyword, and @type {const} for literal values.

    • Not checked by TypeScript
    • Alias @constant

  • @abstract

    TypeScript does not act on the JSDoc @abstract tag, so new Shape() still passes. What tsc does instead, and how to build an abstract class in JavaScript.

    • Not checked by TypeScript
    • Alias @virtual

  • @function, @func and @method

    TypeScript ignores the JSDoc @function, @func and @method tags. Give a variable a function type with @type, or let TypeScript read it from the function.

    • Not checked by TypeScript
    • Alias @func
    • Alias @method

  • @memberof

    TypeScript does not support the JSDoc @memberof tag: it never attaches a function to an object. Assign the function to the object, and TypeScript reads that.

    • Not checked by TypeScript

  • @namespace

    TypeScript ignores the JSDoc @namespace tag: it declares nothing. An object whose properties you assign is the namespace TypeScript reads in a .js file.

    • Not checked by TypeScript

  • @module

    TypeScript does not read the JSDoc @module tag: it never gives a file a module name you can import. Modules are found by path or through package.json.

    • Not checked by TypeScript

The entries on this page are also published as data: tags.json (about the data files).