返回

JS 文档工具，JSDoc 构建企业级网站

前端

JSDoc 的注释，相比于普通注释，带有一个 @ 前缀，@ 之后是 JSDoc 标签，JSDoc 标签有 @function、@class、@typedef 等，这些标签能够对应文档中特定部分，如函数、类和类型定义。

JSDoc 不仅能够利用注释内容自动生成文档，还可以根据注释的内容，帮助我们进行代码检查，保证代码质量，对于一些使用了 TS 的项目，我们甚至可以直接从 JSDoc 注释中为函数、类型等生成 TypeScript 定义文件。

JSDoc 最初的版本是 JSDoc2，后来推出新版本 JSDoc3，虽然 JSDoc3 的使用不如 JSDoc2 普及，但 JSDoc3 能够将生成的文档格式转换为 HTML、Markdown 等多种格式。

JSDoc3 的基本语法格式如下：

/**
 * JSDoc3 注释
 * @function
 * @param {string} x 参数 x 的
 * @returns {string} 返回值 y 的
 */

根据注释内容，JSDoc3 自动生成的 HTML 代码如下：

<dl>
  <dt>x</dt>
  <dd>参数 x 的描述</dd>
</dl>

<dl>
  <dt>Returns:</dt>
  <dd>返回值 y 的描述</dd>
</dl>

我们还可以用 JSDoc3 创建类：

/**
 * JSDoc3 注释
 * @class
 * @param {string} x 参数 x 的描述
 */
class MyClass {
  /**
   * 构造函数
   * @memberof MyClass
   * @param {string} x 参数 x 的描述
   */
  constructor(x) {
    this.x = x;
  }

  /**
   * 成员函数
   * @memberof MyClass
   */
  myMethod() {
    // 方法实现
  }
}

JSDoc3 自动生成的 HTML 代码如下：

<h1>MyClass</h1>

<p>JSDoc3 注释</p>

<h2>Constructor</h2>

<dl>
  <dt>x</dt>
  <dd>参数 x 的描述</dd>
</dl>

<h2>Methods</h2>

<h3>myMethod</h3>
<p>成员函数</p>

JSDoc3 提供丰富的标签类型，我们可以在注释中使用这些标签来对代码进行详细的描述，以方便其他人阅读和理解我们的代码。

JSDoc3 支持多种文档格式，我们可以根据项目的需要选择合适的文档格式。

此外，JSDoc3 还提供了一些工具和扩展来增强文档的生成能力，如 JSDoc3 扩展、JSDoc3 模板等。