deno doc，文档生成器

deno doc [OPTIONS] [source_file]...

deno doc ./path/to/module.ts

deno doc --html --name="My library" ./path/to/module.ts

deno doc --lint ./path/to/module.ts

deno doc ./path/to/module.ts MyClass.someField

deno doc

deno doc --filter Deno.Listener

依赖管理选项 跳转到标题#

--import-map 跳转到标题#

从本地文件或远程 URL 加载导入映射文件。

--lock 跳转到标题#

检查指定的锁定文件。（如果未提供值，则默认为 "./deno.lock"）。

--no-lock 跳转到标题#

禁用自动发现锁定文件。

--no-npm 跳转到标题#

不解析 npm 模块。

--no-remote 跳转到标题#

不解析远程模块。

--reload 跳转到标题#

短标记：-r

重新加载源代码缓存（重新编译 TypeScript）无值 重新加载所有内容 jsr:@std/http/file-server,jsr:@std/assert/assert-equals 重新加载特定模块 npm: 重新加载所有 npm 模块 npm:chalk 重新加载特定 npm 模块。

选项 跳转到标题#

--allow-import 跳转到标题#

短标记：-I

允许从远程主机导入。 可选地指定允许的 IP 地址和主机名，必要时可指定端口。 默认值：deno.land:443,jsr.io:443,esm.sh:443,cdn.jsdelivr.net:443,raw.githubusercontent.com:443,user.githubusercontent.com:443。

文档选项 跳转到标题#

--category-docs 跳转到标题#

指向 JSON 文件的路径，该文件按类别键控，并包含可选的 markdown 文档值。

--default-symbol-map 跳转到标题#

使用提供的默认名称到所需名称的映射，用于用法块。

--filter 跳转到标题#

以点分隔的符号路径。

--html 跳转到标题#

以 HTML 格式输出文档。

--json 跳转到标题#

以 JSON 格式输出文档。

--lint 跳转到标题#

输出文档诊断信息。

--name 跳转到标题#

将在文档中使用的名称（例如，用于面包屑导航）。

--output 跳转到标题#

HTML 文档输出目录。

--private 跳转到标题#

输出私有文档。

--strip-trailing-html 跳转到标题#

从各种链接中删除尾部的 .html。 仍然会生成带有 .html 扩展名的文件。

--symbol-redirect-map 跳转到标题#

指向 JSON 文件的路径，该文件按文件键控，内部映射从符号到外部链接。

示例 跳转到标题#

deno doc 后跟一个或多个源文件列表，将打印每个模块的 导出 成员的 JSDoc 文档。

例如，给定一个内容为 add.ts 的文件

/**
 * Adds x and y.
 * @param {number} x
 * @param {number} y
 * @returns {number} Sum of x and y
 */
export function add(x: number, y: number): number {
  return x + y;
}

运行 Deno doc 命令，将函数的 JSDoc 注释打印到 stdout

deno doc add.ts
function add(x: number, y: number): number
  Adds x and y. @param {number} x @param {number} y @returns {number} Sum of x and y

代码检查 跳转到标题#

你可以使用 --lint 标志来检查你的文档在生成过程中是否存在问题。 deno doc 将指出三种类型的问题

1. 根模块导出的类型引用了非导出的类型时出错。
   • 确保 API 使用者可以访问 API 使用的所有类型。 这可以通过从根模块（在命令行上指定给 deno doc 的文件之一）导出类型或使用 @internal jsdoc 标记标记类型来抑制。
2. 公共 类型缺少返回类型或属性类型时出错。
   • 确保 deno doc 显示返回/属性类型，并有助于提高类型检查性能。
3. 公共 类型缺少 JS doc 注释时出错。
   • 确保代码被记录。 可以通过添加 jsdoc 注释或通过 @ignore jsdoc 标记将其从文档中排除来抑制。 或者，添加 @internal 标签以将其保留在文档中，但表示它是内部的。

例如

interface Person {
  name: string;
  // ...
}

export function getName(person: Person) {
  return person.name;
}

$ deno doc --lint mod.ts
Type 'getName' references type 'Person' which is not exported from a root module.
Missing JS documentation comment.
Missing return type.
    at file:///mod.ts:6:1

这些代码检查旨在帮助你编写更好的文档并加快项目中的类型检查速度。 如果发现任何问题，程序将以非零退出代码退出，并将输出报告给标准错误。

支持的 JSDoc 功能和标签 跳转到标题#

Deno 实现了大量的 JSDoc 标签，但并不严格遵守 JSDoc 标准，而是与广泛使用的工具和生态系统中同一功能空间提供的合理标准和功能保持一致，例如 TSDoc 和 TypeDoc。

对于任何自由格式的文本位置，即 JSDoc 注释的主要描述、参数的描述等，都接受 markdown。

支持的标签 跳转到标题#

以下标签被支持，它们是 JSDoc、TSDoc 和 TypeDoc 使用和指定的标签的精选

• constructor/class：将函数标记为构造函数。
• ignore：忽略要包含在输出中的符号。
• internal：将符号标记为仅供内部使用。 在 HTML 生成器中，该符号不会获得列出的条目，但仍会生成，如果非内部符号链接到它，则可以访问它。
• public：将符号视为公共 API。 等同于 TypeScript public 关键字。
• private：将符号视为私有 API。 等同于 TypeScript private 关键字。
• protected：将属性或方法视为受保护的 API。 等同于 TypeScript protected 关键字。
• readonly：将符号标记为只读，意味着它不能被覆盖。
• experimental：将符号标记为实验性的，意味着 API 可能会更改或删除，或者行为未明确定义。
• deprecated：将符号标记为已弃用，意味着不再支持，并且可能会在未来版本中删除。
• module：此标签可以在顶级 JSDoc 注释中定义，这将使该注释被视为用于文件而不是后续符号。 可以指定一个值，该值将用作模块的标识符（例如，用于默认导出）。
• category/group：将符号标记为属于特定类别/组。 这对于将各种符号组合在一起很有用。
• see：定义与符号相关的外部引用。
• example：为符号定义一个示例。 与 JSDoc 不同，代码示例需要用三反引号（markdown 样式的代码块）包装，这更符合 TSDoc 而不是 JSDoc。
• tags：通过逗号分隔的列表为符号定义额外的自定义标签。
• since：定义符号自何时可用。
• callback：定义回调。
• template/typeparam/typeParam：定义回调。
• prop/property：在符号上定义属性。
• typedef：定义类型。
• param/arg/argument：在函数上定义参数。
• return/returns：定义函数的返回类型和/或注释。
• throws/exception：定义函数在调用时抛出的内容。
• enum：定义一个对象为枚举。
• extends/augments：定义函数扩展的类型。
• this：定义 this 关键字在函数中引用的内容。
• type：定义符号的类型。
• default：定义变量、属性或字段的默认值。

内联链接 跳转到标题#

内联链接允许你指定指向页面其他部分、其他符号或模块的链接。 除了支持 markdown 样式的链接外，还支持 JSDoc 样式的内联链接。

例如，你可以执行 {@link https://docs.deno.org.cn}，它将呈现为以下链接 'https://docs.deno.org.cn'。 也可以使用 {@linkcode https://docs.deno.org.cn}，使其以等宽字体显示，并且大致呈现为这样：'https://docs.deno.org.cn'。

你还可以通过 {@link https://docs.deno.org.cn | Deno Docs} 指定替换标签，它将使用 | 之后的文本作为要显示的文本，而不是链接。 前面的示例将呈现为 'Deno Docs'。

你可以在描述中添加指向其他符号的内联链接，通过 {@link MySymbol}。

对于模块链接，同样适用，但你使用 {@link [myModule]} 语法。 你还可以通过 {@link [myModule].mysymbol} 链接到不同模块中的符号。

HTML 输出 跳转到标题#

使用 --html 标志生成包含文档的静态站点。

$ deno doc --html --name="My library" ./mod.ts

$ deno doc --html --name="My library" --output=./documentation/ ./mod.ts

$ deno doc --html --name="My library" ./sub1/mod.ts ./sub2/mod.ts

生成的文档是一个静态站点，包含多个页面，可以部署到任何静态站点托管服务。

生成的站点中包含客户端搜索，但如果用户的浏览器禁用了 JavaScript，则不可用。

JSON 输出 跳转到标题#

使用 --json 标志以 JSON 格式输出文档。 此 JSON 格式由 deno doc 网站 使用，用于生成模块文档。