Skip to main content

@example

Standardization:Extended
Syntax kind:Block tag

Usage​

Indicates a documentation section that should be presented as an example illustrating how to use the API. It may include a code sample.

Any subsequent text that appears on the same line as the @example tag should be interpreted as a title for the example. Otherwise, the documentation tool can index the examples numerically.

Example A​

For this code sample, the generated titles might be "Example" and "Example 2":


/**
 * Adds two numbers together.
 *
 * @example Here's a simple example:
 *
 * ```
 * // Prints "2":
 * console.log(add(1, 1));
 * ```
 *
 * @example Here's an example with negative numbers:
 *
 * ```
 * // Prints "0":
 * console.log(add(1, -1));
 * ```
 */
export function add(x: number, y: number): number {}

Example B​

For this code sample, the generated title might be "Example: Parsing a basic JSON file":


/**
 * Parses a JSON file.
 *
 * @example Parsing a basic JSON file
 *
 * # Contents of `file.json`
 *
 * ```json
 * {
 *     "exampleItem": "text"
 * }
 * ```
 *
 * # Usage
 *
 * ```ts
 * const result = parseFile("file.json");
 * ```
 *
 * # Result
 *
 * ```ts
 * {
 *     "exampleItem": "text"
 * }
 * ```
 *
 * @param path - Full path to the file.
 *
 * @returns An object containing the JSON data.
 */

See also​