如何用JSDOC 写示例

JSDoc是一种用于JavaScript的注释风格，它不仅可以生成文档，还能帮助开发者理解函数、类等的作用及用法。在JSDoc中，你可以使用特殊的语法来编写示例代码，以便于展示API的用法。下面是一个简单的步骤说明：

1. **添加示例标签**：在你想要提供示例的地方，使用`@example`标签开始。例如：

   /**
   * @example
   * ```
   * const result = addNumbers(5, 7); // 运行结果: 12
   * ```
   */
   function addNumbers(a, b) {
     return a + b;
   }

2. **嵌入代码块**：在`@example`标签后的`{}`内，你可以输入实际的代码片段，通常使用三引号(````)包裹。这里可以包含完整的上下文，包括变量声明和调用。

3. **运行效果**：对于函数调用的结果，可以在代码片段后面加上一个注释，解释预期的输出，如上述例子中的`// 运行结果: 12`。

4. **代码高亮显示**：由于JSDoc支持Markdown语法，你可以使用`hljs`代码高亮插件来提升代码段的可读性。例如，在代码块前添加`hljs.js`或`hljs.typescript`（取决于代码语言）。

5. **自动文档生成**：当你使用工具如Grunt、Gulp或Typdoc解析JSDoc时，这些示例会被自动包含到生成的文档中。

注意：虽然JSDoc支持多种示例格式，比如`@returns`后面的代码片段，但`@example`是最直观和常用的方式，特别是对于复杂的代码流程演示。