工具函数库-注释自动转换md文档

2023-10-29 05:31:23

我们经常会使用lodash、moment等现成的工具函数库，除了通过阅读源码来了解使用外，一般我们还可以通过在线文档或阅读md文档，里面一般都会有详细的使用说明，如果开发一个工具函数库，类比于lodash、moment，此时依旧需要生成说明文档，来对每一个方法进行解释说明，如果开发一个通用方法，就需要自己维护一个用法说明，这必然会增大开发成本，浪费时间，本文档主要介绍的是一种注释自动生成markdown文档的方法，可以大大降低我们生成的文档成本。

简介

如果要生成 markdown 文档，最好的方式当然是能够写出适当的注释，这是一个通用文档构建解决方案。因为我们可以找到一种方法，将注释解析成 markdown 格式，这样就可以从代码中提取必要的信息来生成 markdown。

简单来说，使用该方法之后，您只需对代码进行适当的注释，就可以生成对应的 markdown 文档，而无需再手动编写文档。

操作步骤

下面是通过注释自动生成文档的方法的简单步骤：

编写代码，并以适当的注释对每个函数或类进行。
安装用于生成文档的工具。
运行该工具，将注释提取到 markdown 文件中。
对生成的文档进行修改，使其更符合您的需要。
生成最终的 markdown 文档。

工具选择

Doxygen

Doxygen 是一个用于生成软件文档的工具，它可以从源代码中的注释中提取信息，并将其转换成各种格式的文档，包括 HTML、PDF 和 Markdown。

JSDoc

JSDoc 是一个用于生成 JavaScript 代码的文档的工具，它可以从源代码中的注释中提取信息，并将其转换成多种格式的文档，包括 HTML、PDF 和 Markdown。

typedoc

Typedoc 是一个用于生成 TypeScript 代码的文档的工具，它可以从源代码中的注释中提取信息，并将其转换成多种格式的文档，包括 HTML、PDF 和 Markdown。

使用实例

在代码中，可以使用注释来函数或类的功能、参数和返回值，以及使用示例，如下所示：

/**
 * 计算两个数字的和。
 *
 * @param {number} a 第一个数字。
 * @param {number} b 第二个数字。
 * @returns {number} 两个数字的和。
 */
function add(a, b) {
  return a + b;
}

/**
 * 计算两个数字的差。
 *
 * @param {number} a 第一个数字。
 * @param {number} b 第二个数字。
 * @returns {number} 两个数字的差。
 */
function subtract(a, b) {
  return a - b;
}

然后，可以使用工具将注释提取到 markdown 文件中，如下所示：

## add()

计算两个数字的和。

### 参数

* **a**  第一个数字。
* **b**  第二个数字。

### 返回值

两个数字的和。

### 使用示例

```javascript
const result = add(1, 2);
console.log(result); // 3


## subtract()

计算两个数字的差。

### 参数

* **a**  第一个数字。
* **b**  第二个数字。

### 返回值

两个数字的差。

### 使用示例

```javascript
const result = subtract(4, 2);
console.log(result); // 2


生成 markdown 文档后，可以对其进行修改，使其更符合您的需要，例如，您可以添加标题、图片和表格等。

### 优点

这种方法具有以下优点：

- **自动化：**  该方法可以自动生成文档，无需手动编写。
- **一致性：**  文档与代码紧密相关，因此可以确保文档与代码始终保持一致。
- **可维护性：**  当代码发生变化时，文档也会自动更新。
- **可扩展性：**  该方法可以很容易地扩展到大型项目中。

### 缺点

该方法也有一些缺点：

- **需要编写适当的注释：**  这可能需要花费一些时间。
- **需要安装额外的工具：**  这可能会增加项目的复杂性。

### 结论

注释自动生成 markdown 文档的方法是一种很好的方法，可以帮助您快速生成高质量的文档。如果您正在开发一个工具函数库，那么这种方法非常值得您尝试。