内容

dart doc 命令为 Dart 源代码生成 HTML 参考文档。

编写文档

#

要向生成的文档添加参考文本和示例,请使用带有 文档注释Markdown 格式的 文档注释。有关编写文档注释的指导,请查看 Effective Dart: Documentation 指南。

生成 API 文档

#

要为您的软件包生成文档,请从软件包的根目录运行 dart doc .。例如,为 my_package 软件包生成 API 文档可能类似于以下内容

$ cd my_package
$ dart pub get
$ dart doc .
Documenting my_package...
...
Success! Docs generated into /Users/me/projects/my_package/doc/api

默认情况下,dart doc 将生成的文档和支持文件放置在 doc/api 目录中。要更改输出目录,请使用 --output 标志指定路径

$ dart doc --output=api_docs .

如果您的软件包设置或文档注释有任何问题,dart doc 会将它们输出为错误或警告。如果您只想测试问题而不保存生成的文档,请添加 --dry-run 标志

$ dart doc --dry-run .

配置生成

#

要配置 dart doc 生成文档的方式,请在软件包的根目录中创建一个名为 dartdoc_options.yaml 的文件。

要了解有关文件格式和支持的配置选项的更多信息,请查看 dart.dev/go/dartdoc-options-file

查看生成的文档

#

您可以通过多种方式查看使用 dart doc 生成的文档。

查看本地文档

#

要查看您使用 dart doc 生成的或从网上下载的 API 文档,您必须使用 HTTP 服务器加载它们。

要提供文件,请使用任何 HTTP 服务器。请考虑使用 pub.dev 中的 package:dhttpd

要使用 package:dhttpd,请全局激活它,然后运行它并指定您生成的文档的路径。以下命令激活该软件包,然后运行它以提供位于 doc/api 中的 API 文档

$ dart pub global activate dhttpd
$ dart pub global run dhttpd --path doc/api

然后在浏览器中读取生成的文档,打开 dhttpd 输出的链接,通常为 http://localhost:8080

查看托管的文档

#

您还可以使用支持静态 Web 内容的任何托管服务在线托管您生成的 API 文档。两个常见的选项是 Firebase 托管GitHub 页面

查看软件包文档

#

pub.dev 网站 为上传软件包的公共库生成和托管文档。

要查看软件包生成的文档,请导航到其页面,然后打开页面右侧信息框中的API 参考链接。例如,您可以在 pub.dev/documentation/http 中找到 package:http 的 API 文档。

查看核心库文档

#

dart doc 还用于为 Dart 核心库生成 API 参考文档。

要查看 Dart SDK 参考文档,请访问与您正在开发的 Dart 发行渠道相对应的 api.dart.dev 链接

分支生成的文档
稳定api.dart.dev/stable
测试版api.dart.dev/beta
开发版api.dart.dev/dev
主版本api.dart.dev/main

故障排除

#

要识别和解决使用 dart doc 生成的文档的常见问题,请参阅以下参考部分。

#

如果生成的文档的搜索栏不起作用或包含类似于“初始化搜索失败”的文本,则可能出现以下情况之一

  1. 你正在从自己的文件系统访问文档,但它们尚未通过 HTTP 服务器提供和加载。要了解如何提供本地 API 文档,请查看 如何本地查看生成的文档
  2. dart doc 生成的 index.json 文件缺失或无法从文档目录或托管的 Web 服务器访问。尝试重新生成文档并验证托管配置。

侧边栏加载失败

#

如果生成的文档的侧边栏缺失或包含类似于“加载侧边栏失败”的文本,则可能出现以下情况之一

  1. 你正在从自己的文件系统访问文档,但文档尚未通过 HTTP 服务器提供和加载。要了解如何提供本地 API 文档,请查看 如何查看本地文档
  2. 已配置生成文档的 base-href 行为。此配置选项已弃用,不再应使用。尝试移除该选项并使用 dart doc 的默认行为。如果默认行为破坏了生成文档中的链接,请 提交问题

缺少 API 文档

#

如果你找不到或无法访问你期望有文档的 API 的生成文档,则可能出现以下情况之一

  1. 该软件包未将你要查找的 API 公开为公共 API。dart doc 仅为其他软件包导入和使用的公共库和成员生成文档。要了解有关配置软件包的公共库的更多信息,请查看 公共库 上的软件包布局指南。
  2. 你尝试访问的 URL 大小写不正确。默认情况下,dart doc 生成的文件名区分大小写,与相应的源声明匹配,并具有 .html 扩展名。尝试验证 URL 是否符合这些预期。

应显示图标的文本

#

如果你看到文本而不是图标(如菜单和主题按钮),则你的浏览器可能无法加载 Material Symbols 字体。解决此问题的某些选项包括

  1. 尝试使用允许访问 Google Fonts 服务器的代理。
  2. 更新生成的页面以使用字体的本地版本。