@example holds sample code for a function or class. Editors show it in the hover and while you type a call; VS Code formats the text as a code block. A comment can have several @example tags, and each can start with a <caption>.
The code inside the tag is text. TypeScript 5.9 does not parse or check it, so an example that calls the function with the wrong type, or calls a function that no longer exists, produces no error.
At a glance
| Use | JSDoc in a .js file | TypeScript in a .ts file |
|---|---|---|
| A usage example | /**
* @example
* formatPrice(19.5); // "$19.50"
*/ | /**
* @example
* formatPrice(19.5); // "$19.50"
*/ |
| With a caption | /**
* @example <caption>Another currency</caption>
* formatPrice(19.5, "EUR");
*/ | /**
* @example <caption>Another currency</caption>
* formatPrice(19.5, "EUR");
*/ |
Examples
/**
* Formats a price in dollars.
*
* @example
* formatPrice(19.5); // "$19.50"
* formatPrice("19.5"); // wrong type, but tsc does not read @example code
*
* @param {number} amount
* @returns {string}
*/
export function formatPrice(amount) {
return `$${amount.toFixed(2)}`;
}
formatPrice(19.5);jsconfig.json for this example
{
"compilerOptions": {
"checkJs": true,
"noEmit": true,
"strict": true,
"target": "es2022",
"module": "nodenext",
"types": []
},
"include": ["*.js"]
}/**
* Formats a price in a currency.
*
* @example <caption>Dollars by default</caption>
* formatPrice(19.5); // "$19.50"
*
* @example <caption>Another currency</caption>
* formatPrice(19.5, "EUR"); // "€19.50"
*
* @param {number} amount
* @param {string} [currency]
* @returns {string}
*/
export function formatPrice(amount, currency = "USD") {
return new Intl.NumberFormat("en-US", { style: "currency", currency }).format(amount);
}
formatPrice(19.5, "EUR");jsconfig.json for this example
{
"compilerOptions": {
"checkJs": true,
"noEmit": true,
"strict": true,
"target": "es2022",
"module": "nodenext",
"types": []
},
"include": ["*.js"]
}What editors show
TypeScript passes the tag's text to the editor unchanged. VS Code's TypeScript support wraps it in a code fence, so it appears highlighted in the hover; it also turns a leading <caption> into a caption line. Other editors show the text as written.
An example runs until the next tag. Put @param, @returns and the rest before or after the sample code, never in the middle of it.
Keeping examples honest
Because nothing checks the code in @example, it is worth keeping it short and keeping the real usage in tests or in checked files. This site takes the second route: every example above is a real file run through tsc, while the code inside its @example tags is not.
Gotchas
- An
@at the start of a line in the example, such as a decorator, starts a new tag; an email address in the middle of a line stays part of the example (checked with the language service of TypeScript 5.9). Keep decorators out of@example.
Questions
Does TypeScript type-check code in @example?
No. The first example on this page passes a string to a function that takes a number inside @example, and tsc reports nothing.
Sources
- @example · JSDoc
- VS Code: how JSDoc tags are rendered in hovers (textRendering.ts) · Microsoft, VS Code source
- JSDoc Reference · TypeScript handbook
Last reviewed 20 October 2026.