什么是 fast-extract？
fast-extract 是一个可以快速解析 JavaScript（或 TypeScript）源码中的注释信息的工具。当你需要从代码注释中提取一些有用信息，比如 API 接口文档、代码示例等等时，fast-extract 就能派上用场。它支持多种注释格式，包括 JSDoc、TypeDoc 等，也可以自定义格式。
fast-extract 的安装和使用
安装
fast-extract 是一个 npm 包，你可以直接使用 npm 安装。
npm install fast-extract --save-dev
使用
使用 fast-extract 非常简单，只需要在命令行中输入以下命令：
fast-extract --src [src] --out [out]
其中，[src] 表示要解析的源代码文件夹路径，[out] 表示解析结果输出的文件路径。例如：
fast-extract --src src --out api.md
这个命令将会解析 src 文件夹下的所有 JavaScript 文件，并将提取到的注释信息保存到 api.md 文件中。
fast-extract 默认支持的注释格式为 JSDoc，如果你的代码采用其他注释格式，可以使用 --comment-format 参数指定。例如：
fast-extract --src src --out api.md --comment-format typedoc
fast-extract 的进阶用法
支持自定义注释格式
当你的代码注释格式和默认支持的 JSDoc 不一致时，就需要自定义注释格式。fast-extract 提供了一个非常方便的方式来实现自定义注释格式。
以下是一个自定义注释格式的例子：
-- -------------------- ---- ------- -- -------------- -- ----- -------------- -- ---------- --------------------- -- -------- - -- ------------ -- ------- ------ --- ------------ -- --------------- -------- ------ - -- ------------- -- -------- -- ------------------- ---------------- - -------
上述代码采用 Tampermonkey UserScript 的注释格式，并使用 @example 标签来标注示例代码。为了让 fast-extract 能够识别这个注释格式，我们需要定义一个注释配置文件。在根目录下创建一个名为 extractor.config.js 的文件，文件内容如下：
-- -------------------- ---- -------
-------------- - -
--------- -
-------- --------- -- -
----- ------ - --------------------------------------------------------------------
------ -------
-----
-------- -
-
------ ---------------------------------
--- ----------
-------- --
-
-
-
--上文 comments 是一个对象，它包含两个属性：
pattern表示注释的正则表达式。这个正则表达式可以根据实际情况自行定义。collect表示需要提取的注释标签。这个数组中包含多个对象，每个对象都包含以下属性：match表示该标签的正则表达式。to表示将提取到的信息输出到哪个字段中。replace表示要替换掉该标签的正则表达式。
配置完成后，我们可以再次运行 fast-extract 来提取代码中的注释信息了：
fast-extract --src src --out api.md --extractor-config extractor.config.js
在命令中加入上述参数，即可使用自定义注释格式来提取注释信息。
使用提取到的信息
fast-extract 默认是将注释信息保存到一个 Markdown 文件中。但如果你希望得到更灵活的输出结果，比如生成 HTML 文件、渲染页面等，那么可以使用 Markdown 渲染工具来使用提取到的信息。下面是一个例子：
-- -------------------- ---- -------
----- -- - --------------
----- ------ - ------------------
--------------------- ------- -------- ----- ----- -
-- ----- ----- ----
----- ---- - -------------
------------------------ ----- -------- ----- -
-- ----- ----- ----
----------------------- --------- ----------------
---
---上述代码将会把 api.md 中的 Markdown 格式转换成 HTML 格式，并保存到 api.html 文件中。
总结
fast-extract 是一个非常实用的工具，可以帮助我们快速解析代码注释信息。除了默认支持的 JSDoc 注释格式外，它还支持自定义注释格式，非常方便地满足各种实际需求。在日常开发工作中，善于使用这种工具，不仅可以提高效率，还能保证代码的质量。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/5f5309bf8250f93ef890043b