The list below outlines which constructs are currently supported\nwhen using JSDoc annotations to provide type information in JavaScript files.
\nNote any tags which are not explicitly listed below (such as @async) are not yet supported.
@type@param (or @arg or @argument)@returns (or @return)@typedef@callback@template@class (or @constructor)@this@extends (or @augments)@enumThe meaning is usually the same, or a superset, of the meaning of the tag given at jsdoc.app.\nThe code below describes the differences and gives some example usage of each tag.
\nNote: You can use the playground to explore JSDoc support.
\n@typeYou can use the “@type” tag and reference a type name (either primitive, defined in a TypeScript declaration, or in a JSDoc “@typedef” tag).\nYou can use most JSDoc types and any TypeScript type, from the most basic like string to the most advanced, like conditional types.
\njs/**\n * @type {string}\n */\nvarTrys ;\n\n/** @type {Window} */\nvarwin ;\n\n/** @type {PromiseLike<string>} */\nvarpromisedString ;\n\n// You can specify an HTML Element with DOM properties\n/** @type {HTMLElement} */\nvarmyElement =document .querySelector (selector );\nelement .dataset .myData = \"\";
@type can specify a union type — for example, something can be either a string or a boolean.
\njs/**\n * @type {(string | boolean)}\n */\nvarTrysb ;
Note that parentheses are optional for union types.
\n\njs/**\n * @type {string | boolean}\n */\nvarTrysb ;
You can specify array types using a variety of syntaxes:
\n\njs/** @type {number[]} */\nvarTryns ;\n/** @type {Array.<number>} */\nvarnds ;\n/** @type {Array<number>} */\nvarnas ;
You can also specify object literal types.\nFor example, an object with properties ‘a’ (string) and ‘b’ (number) uses the following syntax:
\n\njs/** @type {{ a: string, b: number }} */\nvarTryvar9 ;
You can specify map-like and array-like objects using string and number index signatures, using either standard JSDoc syntax or TypeScript syntax.
\n\njs/**\n * A map-like object that maps arbitrary `string` properties to `number`s.\n *\n * @type {Object.<string, number>}\n */\nvarTrystringToNumber ;\n\n/** @type {Object.<number, object>} */\nvararrayLike ;
The preceding two types are equivalent to the TypeScript types { [x: string]: number } and { [x: number]: any }. The compiler understands both syntaxes.
You can specify function types using either TypeScript or Closure syntax:
\n\njs/** @type {function(string, boolean): number} Closure syntax */\nvarTrysbn ;\n/** @type {(s: string, b: boolean) => number} TypeScript syntax */\nvarsbn2 ;
Or you can just use the unspecified Function type:
\njs/** @type {Function} */\nvarTryfn7 ;\n/** @type {function} */\nvarfn6 ;
Other types from Closure also work:
\n\njs/**\n * @type {*} - can be 'any' type\n */\nvarTrystar ;\n/**\n * @type {?} - unknown type (same as 'any')\n */\nvarquestion ;
TypeScript borrows cast syntax from Closure.\nThis lets you cast types to other types by adding a @type tag before any parenthesized expression.
\njs/**\n * @type {number | string}\n */\nvarTrynumberOrString =Math .random () < 0.5 ? \"hello\" : 100;\nvartypeAssertedNumber = /** @type {number} */ (numberOrString );
You can also import declarations from other files using import types.\nThis syntax is TypeScript-specific and differs from the JSDoc standard:
\n\njs// @filename: types.d.ts\nexport typeTryPet = {\nname : string,\n};\n\n// @filename: main.js\n/**\n * @param p { import(\"./types\").Pet }\n */\nfunctionwalk (p ) {\nconsole .log (`Walking ${p .name }...`);\n}
import types can also be used in type alias declarations:
\n\njs/**\n * @typedef { import(\"./types\").Pet } Pet\n */\n\n/**\n * @type {Pet}\n */\nvarTrymyPet ;\nmyPet .name ;
import types can be used to get the type of a value from a module if you don’t know the type, or if it has a large type that is annoying to type:
\n\njs/**\n * @type {typeof import(\"./accounts\").userAccount }\n */\nvarTryx =require (\"./accounts\").userAccount ;
@param and @returns@param uses the same type syntax as @type, but adds a parameter name.\nThe parameter may also be declared optional by surrounding the name with square brackets:
\njs// Parameters may be declared in a variety of syntactic forms\n/**\n * @param {string} p1 - A string param.\n * @param {string=} p2 - An optional param (Closure syntax)\n * @param {string} [p3] - Another optional param (JSDoc syntax).\n * @param {string} [p4=\"test\"] - An optional param with a default value\n * @return {string} This is the result\n */\nfunctionTrystringsStringStrings (p1 ,p2 ,p3 ,p4 ) {\n // TODO\n}
Likewise, for the return type of a function:
\n\njs/**\n * @return {PromiseLike<string>}\n */\nfunctionTryps () {}\n\n/**\n * @returns {{ a: string, b: number }} - May use '@returns' as well as '@return'\n */\nfunctionab () {}
@typedef, @callback, and @param@typedef may be used to define complex types.\nSimilar syntax works with @param.
\njs/**\n * @typedef {Object} SpecialType - creates a new type named 'SpecialType'\n * @property {string} prop1 - a string property of SpecialType\n * @property {number} prop2 - a number property of SpecialType\n * @property {number=} prop3 - an optional number property of SpecialType\n * @prop {number} [prop4] - an optional number property of SpecialType\n * @prop {number} [prop5=42] - an optional number property of SpecialType with default\n */\n\n/** @type {SpecialType} */\nvarTryspecialTypeObject ;\nspecialTypeObject .prop3 ;
You can use either object or Object on the first line.
\njs/**\n * @typedef {object} SpecialType1 - creates a new type named 'SpecialType'\n * @property {string} prop1 - a string property of SpecialType\n * @property {number} prop2 - a number property of SpecialType\n * @property {number=} prop3 - an optional number property of SpecialType\n */\n\n/** @type {SpecialType1} */\nvarTryspecialTypeObject1 ;
@param allows a similar syntax for one-off type specifications.\nNote that the nested property names must be prefixed with the name of the parameter:
\njs/**\n * @param {Object} options - The shape is the same as SpecialType above\n * @param {string} options.prop1\n * @param {number} options.prop2\n * @param {number=} options.prop3\n * @param {number} [options.prop4]\n * @param {number} [options.prop5=42]\n */\nfunctionTryspecial (options ) {\n return (options .prop4 || 1001) +options .prop5 ;\n}
@callback is similar to @typedef, but it specifies a function type instead of an object type:
\njs/**\n * @callback Predicate\n * @param {string} data\n * @param {number} [index]\n * @returns {boolean}\n */\n\n/** @type {Predicate} */\nconstTryok = (s ) => !(s .length % 2);
Of course, any of these types can be declared using TypeScript syntax in a single-line @typedef:
\njs/** @typedef {{ prop1: string, prop2: string, prop3?: number }} SpecialType */\n/** @typedef {(data: string, index?: number) => boolean} Predicate */
@templateYou can declare generic functions with the @template tag:
\njs/**\n * @template T\n * @param {T} x - A generic parameter that flows through to the return type\n * @return {T}\n */\nfunctionTryid (x ) {\n returnx ;\n}\n\nconsta =id (\"string\");\nconstb =id (123);\nconstc =id ({});
Use comma or multiple tags to declare multiple type parameters:
\n\njs/**\n * @template T,U,V\n * @template W,X\n */
You can also specify a type constraint before the type parameter name.\nOnly the first type parameter in a list is constrained:
\n\njs/**\n * @template {string} K - K must be a string or string literal\n * @template {{ serious(): string }} Seriousalizable - must have a serious method\n * @param {K} key\n * @param {Seriousalizable} object\n */\nfunctionTryseriousalize (key ,object ) {\n // ????\n}
Declaring generic classes or types is unsupported.
\nClasses can be declared as ES6 classes.
\n\njsclassTryC {\n /**\n * @param {number} data\n */\n constructor(data ) {\n // property types can be inferred\n this.name = \"foo\";\n\n // or set explicitly\n /** @type {string | null} */\n this.title = null;\n\n // or simply annotated, if they're set elsewhere\n /** @type {number} */\n this.size ;\n\n this.initialize (data ); // Should error, initializer expects a string\n }\n /**\n * @param {string} s\n */\ninitialize = function (s ) {\n this.size =s .length ;\n };\n}\n\nvarc = newC (0);\n\n// C should only be called with new, but\n// because it is JavaScript, this is allowed and\n// considered an 'any'.\nvarresult =C (1);
They can also be declared as constructor functions, as described in the next section:
\n@constructorThe compiler infers constructor functions based on this-property assignments, but you can make checking stricter and suggestions better if you add a @constructor tag:
\njs/**\n * @constructor\n * @param {number} data\n */\nfunctionTryC (data ) {\n // property types can be inferred\n this.name = \"foo\";\n\n // or set explicitly\n /** @type {string | null} */\n this.title = null;\n\n // or simply annotated, if they're set elsewhere\n /** @type {number} */\n this.size ;\n\n this.initialize ();\nArgument of type 'number' is not assignable to parameter of type 'string'.2345Argument of type 'number' is not assignable to parameter of type 'string'.}\n/**\n * @param {string} s\n */\n data C .prototype .initialize = function (s ) {\n this.size =s .length ;\n};\n\nvarc = newC (0);\nc .size ;\n\nvarresult =C (1);\nValue of type 'typeof C' is not callable. Did you mean to include 'new'?2348Value of type 'typeof C' is not callable. Did you mean to include 'new'?
\n\nNote: Error messages only show up in JS codebases with a JSConfig and
\ncheckJsenabled.
With @constructor, this is checked inside the constructor function C, so you will get suggestions for the initialize method and an error if you pass it a number. Your editor may also show warnings if you call C instead of constructing it.
Unfortunately, this means that constructor functions that are also callable cannot use @constructor.
@thisThe compiler can usually figure out the type of this when it has some context to work with. When it doesn’t, you can explicitly specify the type of this with @this:
\njs/**\n * @this {HTMLElement}\n * @param {*} e\n */\nfunctionTrycallbackForLater (e ) {\n this.clientHeight =parseInt (e ); // should be fine!\n}
@extendsWhen Javascript classes extend a generic base class, there is nowhere to specify what the type parameter should be. The @extends tag provides a place for that type parameter:
\njs/**\n * @template T\n * @extends {Set<T>}\n */\nclassTrySortableSet extendsSet {\n // ...\n}
Note that @extends only works with classes. Currently, there is no way for a constructor function extend a class.
@enumThe @enum tag allows you to create an object literal whose members are all of a specified type. Unlike most object literals in Javascript, it does not allow other members.
\njs/** @enum {number} */\nconstTryJSDocState = {\nBeginningOfLine : 0,\nSawAsterisk : 1,\nSavingComments : 2,\n};\n\nJSDocState .SawAsterisk ;
Note that @enum is quite different from, and much simpler than, TypeScript’s enum. However, unlike TypeScript’s enums, @enum can have any type:
\njs/** @enum {function(number): number} */\nconstTryMathFuncs = {\nadd1 : (n ) =>n + 1,\nid : (n ) => -n ,\nsub1 : (n ) =>n - 1,\n};\n\nMathFuncs .add1 ;
\njsvarTrysomeObj = {\n /**\n * @param {string} param1 - Docs on property assignments work\n */\nx : function (param1 ) {},\n};\n\n/**\n * As do docs on variable assignments\n * @return {Window}\n */\nletsomeFunc = function () {};\n\n/**\n * And class methods\n * @param {string} greeting The greeting to use\n */\nFoo .prototype .sayHi = (greeting ) =>console .log (\"Hi!\");\n\n/**\n * And arrow functions expressions\n * @param {number} x - A multiplier\n */\nletmyArrow = (x ) =>x *x ;\n\n/**\n * Which means it works for stateless function components in JSX too\n * @param {{a: string, b: number}} test - Some param\n */\nvarsfc = (test ) => <div >{test .a .charAt (0)}</div >;\n\n/**\n * A parameter can be a class constructor, using Closure syntax.\n *\n * @param {{new(...args: any[]): object}} C - The class to register\n */\nfunctionregisterClass (C ) {}\n\n/**\n * @param {...string} p1 - A 'rest' arg (array) of strings. (treated as 'any')\n */\nfunctionfn10 (p1 ) {}\n\n/**\n * @param {...string} p1 - A 'rest' arg (array) of strings. (treated as 'any')\n */\nfunctionfn9 (p1 ) {\n returnp1 .join ();\n}
Referring to objects in the value space as types doesn’t work unless the object also creates a type, like a constructor function.
\n\njsfunctionTryaNormalFunction () {}\n/**\n * @type {aNormalFunction}\n */\nvarwrong ;\n/**\n * Use 'typeof' instead:\n * @type {typeof aNormalFunction}\n */\nvarright ;
Postfix equals on a property type in an object literal type doesn’t specify an optional property:
\n\njs/**\n * @type {{ a: string, b: number= }}\n */\nvarTrywrong ;\n/**\n * Use postfix question on the property name instead:\n * @type {{ a: string, b?: number }}\n */\nvarright ;
Nullable types only have meaning if strictNullChecks is on:
\njs/**\n * @type {?number}\n * With strictNullChecks: true -- number | null\n * With strictNullChecks: false -- number\n */\nvarTrynullable ;
You can also use a union type:
\n\njs/**\n * @type {number | null}\n * With strictNullChecks: true -- number | null\n * With strictNullChecks: false -- number\n */\nvarTryunionNullable ;
Non-nullable types have no meaning and are treated just as their original type:
\n\njs/**\n * @type {!number}\n * Just has type number\n */\nvarTrynormal ;
Unlike JSDoc’s type system, TypeScript only allows you to mark types as containing null or not.\nThere is no explicit non-nullability — if strictNullChecks is on, then number is not nullable.\nIf it is off, then number is nullable.
TypeScript ignores any unsupported JSDoc tags.
\nThe following tags have open issues to support them:
\n@const (issue #19672)@inheritdoc (issue #23215)@memberof (issue #7237)@readonly (issue #17233)@yields (issue #23857){@link …} (issue #16498)