deno doc
,文档生成器
命令行用法
deno doc [OPTIONS] [source_file]...
显示模块文档。
将文档输出到标准输出
deno doc ./path/to/module.ts
以 HTML 格式输出文档
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
依赖管理选项 跳转到标题
--frozen
跳转到标题
如果锁定文件过期,则报错。
--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。
--deny-import
跳转到标题
拒绝从远程主机导入。可选择指定拒绝的 IP 地址和主机名,必要时包含端口。
文档选项 跳转到标题
--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
将指出三类问题:
- 根模块中导出的类型引用非导出类型的错误。
- 确保 API 使用者可以访问 API 使用的所有类型。这可以通过从根模块(命令行上为
deno doc
指定的文件之一)导出类型来抑制,或者通过用@internal
jsdoc 标签标记类型来抑制。
- 确保 API 使用者可以访问 API 使用的所有类型。这可以通过从根模块(命令行上为
- 公共类型缺少返回类型或属性类型的错误。
- 确保
deno doc
显示返回/属性类型并有助于提高类型检查性能。
- 确保
- 公共类型缺少 JS doc 注释的错误。
- 确保代码有文档。可以通过添加 jsdoc 注释来抑制,或者通过
@ignore
jsdoc 标签将其从文档中排除。或者,添加@internal
标签以将其保留在文档中,但表明它是内部的。
- 确保代码有文档。可以通过添加 jsdoc 注释来抑制,或者通过
例如
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 网站使用,用于生成模块文档。