@example

标准化	扩展
语法种类	块标签

用法

指示一个文档章节，该章节应作为示例展示如何使用 API。它可能包含代码示例。

在与 @example 标签同一行出现的任何后续文本都应被解释为示例的标题。否则，文档工具可以按数字索引示例。

示例 A

对于此代码示例，生成的标题可能是 “示例” 和 “示例 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 {}

示例 B

对于此代码示例，生成的标题可能是 “示例：解析基本的 JSON 文件”

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

另请参阅

• RFC #20: @example 标签的语法