The description of a function is the text at the top of its JSDoc comment, before the first tag. Editors show it under the signature when you hover the name or type a call. TypeScript treats it as documentation only: nothing in it is checked.
@description (also @desc) and @summary are JSDoc documentation tags for the same purpose. TypeScript 5.9 keeps them as ordinary tags: the hover shows them after the signature as @description and @summary lines, not as the main text. For TypeScript users, plain text at the top of the comment works best.
At a glance
| Use | JSDoc in a .js file | TypeScript in a .ts file |
|---|---|---|
| The main description | /**
* Works out the shipping charge.
* @param {number} subtotal
*/ | /**
* Works out the shipping charge.
* @param subtotal
*/ |
| A one-line summary | /** @summary Shipping charge for a cart. */ | /** @summary Shipping charge for a cart. */ |
Examples
/**
* Works out the shipping charge for a cart, in dollars.
*
* Orders over $50 ship free.
*
* @summary Shipping charge for a cart.
* @param {number} subtotal
* @returns {number}
*/
export function shippingFor(subtotal) {
return subtotal > 50 ? 0 : 4.95;
}
// In the hover, this text appears as a tag below the signature, not as the main description.
/**
* @description Works out the tax for a cart.
* @param {number} subtotal
* @returns {number}
*/
export function taxFor(subtotal) {
return Math.round(subtotal * 0.08 * 100) / 100;
}
shippingFor(42);
taxFor(42);jsconfig.json for this example
{
"compilerOptions": {
"checkJs": true,
"noEmit": true,
"strict": true,
"target": "es2022",
"module": "nodenext",
"types": []
},
"include": ["*.js"]
}/**
* Works out the shipping charge from `subtotl` (misspelled on purpose:
* TypeScript does not check names in the description).
*
* @param {number} subtotal
* @returns {number}
*/
export function shippingFor(subtotal) {
return subtotal > 50 ? 0 : 4.95;
}jsconfig.json for this example
{
"compilerOptions": {
"checkJs": true,
"noEmit": true,
"strict": true,
"target": "es2022",
"module": "nodenext",
"types": []
},
"include": ["*.js"]
}What editors show
We asked TypeScript's language service, the code editors call for hovers, about both functions in the first example. For shippingFor, the documentation is the text above the tags, and @summary comes back as a separate tag. For taxFor, whose comment starts with @description, the main documentation is empty and the text comes back as a tag named description.
Descriptions can use Markdown in most editors, and {@link} turns a name into a link to its declaration.
Gotchas
- Names and types in the description are not checked: a misspelled parameter name in the text stays misspelled, as the second example shows. Only the tags with types (
@param,@returns,@typeand the rest) are read by the checker. - An
@followed by a word starts a new tag, even in the middle of a sentence. Put such text in backticks or reword it.
Questions
Do I need @description in a TypeScript project?
No. Write the description as the first lines of the comment. Keep @description only if a documentation tool you use requires it.
Sources
- @description · JSDoc
- @summary · JSDoc
- JSDoc Reference · TypeScript handbook
Last reviewed 20 October 2026.