On this page
使用 deno doc 生成文档
良好的文档对任何软件项目都至关重要。它帮助其他开发者理解您的代码，简化维护，提高项目的整体质量。Deno 内置了一个名为 deno doc 的文档生成器，可以从您的 TypeScript 和 JavaScript 代码自动生成可搜索的文档。
deno doc 开箱即用，无需任何配置，可生成 HTML、JSON 或终端输出。它利用 JSDoc 注释进行文档编写，同时会自动提取代码中 TypeScript 类型注解的信息。
使用 JSR 自动生成文档
如果您将包发布到
JSR（JavaScript 注册中心），则可以免费自动获得美观的文档生成！JSR 在底层使用相同的 deno doc 技术，为所有发布的包创建可搜索的网页文档。只需通过 deno publish 发布带有完善文档的代码，JSR 将为您完成剩余工作。
创建示例项目 Jump to heading
让我们创建一个示例库来演示 deno doc 的功能。我们将构建一个带有良好文档的简单数学工具库。
math.ts
/**
* 一组数学工具函数集合。
* @module
*/
/**
* 将两个数字相加。
*
* @example
* ```ts
* import { add } from "./math.ts";
*
* const result = add(5, 3);
* console.log(result); // 8
* ```
*
* @param x 第一个数字
* @param y 第二个数字
* @returns x 和 y 之和
*/
export function add(x: number, y: number): number {
return x + y;
}
/**
* 将两个数字相乘。
*
* @example
* ```ts
* import { multiply } from "./math.ts";
*
* const result = multiply(4, 3);
* console.log(result); // 12
* ```
*
* @param x 第一个数字
* @param y 第二个数字
* @returns x 和 y 的乘积
*/
export function multiply(x: number, y: number): number {
return x * y;
}
/**
* 表示二维空间中的一个点。
*
* @example
* ```ts
* import { Point } from "./math.ts";
*
* const point = new Point(5, 10);
* console.log(point.distance()); // 11.180339887498949
* ```
*/
export class Point {
/**
* 创建一个新的 Point 实例。
*
* @param x x 坐标
* @param y y 坐标
*/
constructor(public x: number, public y: number) {}
/**
* 计算该点到原点 (0, 0) 的距离。
*
* @returns 到原点的距离
*/
distance(): number {
return Math.sqrt(this.x * this.x + this.y * this.y);
}
/**
* 计算该点到另一个点的距离。
*
* @param other 另一个点
* @returns 两点之间的距离
*/
distanceTo(other: Point): number {
const dx = this.x - other.x;
const dy = this.y - other.y;
return Math.sqrt(dx * dx + dy * dy);
}
}
/**
* 数学操作的配置选项。
*/
export interface MathConfig {
/** 浮点计算的精度 */
precision?: number;
/** 是否将结果四舍五入为整数 */
roundToInt?: boolean;
}
/**
* 在配置下执行高级数学运算。
*
* @example
* ```ts
* import { calculate } from "./math.ts";
*
* const result = calculate(10, 3, { precision: 2, roundToInt: false });
* console.log(result); // 3.33
* ```
*/
export function calculate(
dividend: number,
divisor: number,
config: MathConfig = {},
): number {
const { precision = 10, roundToInt = false } = config;
let result = dividend / divisor;
if (roundToInt) {
result = Math.round(result);
} else {
result = Math.round(result * Math.pow(10, precision)) /
Math.pow(10, precision);
}
return result;
}
基础文档生成 Jump to heading
生成文档最简单的方式是对源文件运行 deno doc：
deno doc math.ts
这会在您的终端输出文档，显示所有导出的函数、类和接口及其 JSDoc 注释。
生成 HTML 格式文档 Jump to heading
若要创建包含 HTML、CSS 和 JS 的文档网站，使用 --html 标志：
deno doc --html --name="数学工具" math.ts
这将在 ./docs/ 目录生成静态网站。该站点包括：
- 可搜索的界面
- 语法高亮
- 符号间的交叉引用
- 移动端友好的响应式设计
您还可以指定自定义输出目录：
deno doc --html --name="数学工具" --output=./documentation/ math.ts
文档规范检查 Jump to heading
使用 --lint 标志检查文档问题：
deno doc --lint math.ts
它会报告多种问题：
- 导出函数、类或接口缺少 JSDoc 注释
- 函数缺少返回类型注释
- 导出符号引用了未导出的类型
我们创建一个带有一些文档问题的文件，来查看 linter 的表现：
bad_example.ts
// 缺少 JSDoc 注释
export function badFunction(x) {
return x * 2;
}
interface InternalType {
value: string;
}
// 引用了未导出的类型
export function anotherFunction(param: InternalType) {
return param.value;
}
运行 deno doc --lint bad_example.ts 会显示这些问题的错误。
同时处理多个文件 Jump to heading
您可以同时文档多个文件：
deno doc --html --name="我的库" ./mod.ts ./utils.ts ./types.ts
对于较大项目，创建一个重新导出所有内容的主模块文件：
mod.ts
/**
* 数学工具库
*
* 一个完整的数学函数和工具集合。
*
* @example
* ```ts
* import { add, multiply, Point } from "./mod.ts";
*
* const sum = add(5, 3);
* const product = multiply(4, 2);
* const point = new Point(3, 4);
* ```
*
* @module
*/
export * from "./math.ts";
然后从主模块生成文档：
deno doc --html --name="数学工具" mod.ts
用于自动化的 JSON 输出 Jump to heading
生成 JSON 格式的文档以便与其他工具配合使用：
deno doc --json math.ts > documentation.json
JSON 输出提供了代码结构的底层表示，包括符号定义和基本类型信息。此格式主要用于构建自定义文档工具或集成需要程序化访问代码 API 的系统。
JSDoc 注释的最佳实践 Jump to heading
使用 deno doc 时，请遵循以下 JSDoc 最佳实践：
1. 使用描述性的摘要 Jump to heading
/**
* 使用递归计算一个数字的阶乘。
*
* @param n 要计算阶乘的数字
* @returns n 的阶乘
*/
export function factorial(n: number): number {
// 实现...
}
2. 提供具体示例 Jump to heading
/**
* 将数字格式化为货币形式。
*
* @example
* ```ts
* formatCurrency(123.456); // "$123.46"
* formatCurrency(1000); // "$1,000.00"
* ```
*
* @param amount 要格式化的金额
* @returns 格式化后的货币字符串
*/
export function formatCurrency(amount: number): string {
// 实现...
}
3. 注明参数和返回值 Jump to heading
/**
* 验证邮箱地址格式。
*
* @param email 要验证的邮箱地址
* @returns 若格式有效返回 true，否则返回 false
* @throws {Error} 当邮箱为 null 或 undefined 时抛出
*/
export function validateEmail(email: string): boolean {
// 实现...
}
4. 使用模块级文档 Jump to heading
/**
* 邮箱验证工具。
*
* 本模块提供根据 RFC 5322 标准验证和格式化邮箱地址的函数。
*
* @module
*/
5. 标记废弃或实验性功能 Jump to heading
/**
* 兼容旧版的遗留函数。
*
* @deprecated 请使用 `newFunction()` 替代
* @param data 输入数据
*/
export function oldFunction(data: string): void {
// 实现...
}
/**
* 新的实验性功能。
*
* @experimental 此 API 未来版本可能发生变更
* @param options 配置选项
*/
export function experimentalFunction(options: unknown): void {
// 实现...
}
集成至 CI/CD 流程 Jump to heading
您可以将文档生成集成到持续集成管道中：
.github/workflows/docs.yml
name: 生成文档
on:
push:
branches: [main]
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: 设置 Deno
uses: denoland/setup-deno@v2
with:
deno-version: v2.x
- name: 生成文档
run: deno doc --html --name="我的库" --output=./docs/ mod.ts
- name: 部署到 GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs
在 deno.json 中配置 Jump to heading
您可以在 deno.json 文件中配置文档生成：
deno.json
{
"tasks": {
"doc": "deno doc --html --name='数学工具' --output=./docs/ mod.ts",
"doc:lint": "deno doc --lint mod.ts",
"doc:json": "deno doc --json mod.ts > documentation.json"
}
}
然后轻松运行文档相关任务：
deno task doc
deno task doc:lint
deno task doc:json
🦕 deno doc 命令是一个强大的工具，用于从您的 Deno 项目生成专业文档。
良好的文档让您的代码更易维护，帮助其他开发者有效理解和使用您的项目。使用 deno doc，全面的文档仅需一条命令！