dart doc
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 Hosting 和 GitHub Pages。
查看包文档
#pub.dev 站点会为上传的包的公共库生成并托管文档。
要查看包的生成文档，请导航到其页面，并打开页面右侧信息框中的API 参考链接。例如，您可以在 pub.dev/documentation/http 找到 package:http 的 API 文档。
查看核心库文档
#dart doc 也用于为 Dart 核心库生成 API 参考文档。
要查看 Dart SDK 参考文档，请访问与您正在使用的 Dart 发布渠道对应的 api.dart.dev 链接
| 分支 | 生成的文档 |
|---|---|
stable | api.dart.dev/stable |
beta | api.dart.dev/beta |
dev | api.dart.dev/dev |
main | api.dart.dev/main |
故障排除
#要识别和解决使用 dart doc 生成文档的常见问题，请参阅以下参考部分。
搜索栏加载失败
#如果生成的文档的搜索栏无法使用或包含类似“初始化搜索失败”的文本，则可能出现以下情况之一
- 您正在从自己的文件系统访问文档，但它们没有通过 HTTP 服务器提供服务和加载。要了解如何提供本地 API 文档服务，请查看如何查看本地生成的文档。
dart doc生成的index.json文件丢失，或无法从文档目录或您的托管 Web 服务器访问。请尝试重新生成文档并验证您的托管配置。
侧边栏加载失败
#如果生成的文档的侧边栏丢失或包含类似“加载侧边栏失败”的文本，则可能出现以下情况之一
- 您正在从自己的文件系统访问文档，但文档没有通过 HTTP 服务器提供服务和加载。要了解如何提供本地 API 文档服务，请查看如何查看本地文档。
- 已配置生成的文档的 base-href 行为。此配置选项已弃用，不应再使用。请尝试删除该选项并使用
dart doc的默认行为。如果默认行为导致生成的文档中的链接损坏，请提交问题。
缺少 API 文档
#如果您找不到或无法访问您认为应该有文档的 API 的生成文档，则可能出现以下情况之一
- 该包没有将您要查找的 API 作为公共 API 公开。
dart doc只为公开给其他包导入和使用的公共库和成员生成文档。要了解更多关于配置包的公共库的信息，请查看包布局指南中的公共库部分。 - 您尝试访问的 URL 大小写不正确。默认情况下，
dart doc生成的文件名是区分大小写的，与相应的源代码声明匹配，并具有.html扩展名。请尝试验证 URL 是否符合这些预期。
图标位置显示文本
#如果您看到文本而不是菜单和主题按钮等图标，则可能是您的浏览器无法加载 Material Symbols 字体。解决此问题的一些选项包括
- 尝试使用允许访问 Google Fonts 服务器的代理。
- 更新生成的页面以使用本地版本的字体。