deno doc，文档生成器

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. 错误：公共类型缺少 JSDoc 注释。
   • 确保代码已记录。可以通过添加 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

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

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 网站 使用，用于生成模块文档。