使用 dartdoc 注释编写文档
编写可在 pub.dev 上呈现的文档
使用 dartdoc 注释编写文档 是 CoddyKit 上的免费 Dart Academy 课时。 这是第 2 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 Dart Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Dart Academy 课程共包含 4 节课。
文档也是产品的一部分
优秀的软件包也应配有优秀的文档。Dart 会将特殊注释转换为可浏览的参考资料，因此文档是首要功能，而不是事后补充。📝
三斜线文档注释
文档注释以三个斜线开头。这些文档注释紧邻声明上方，用于向用户说明声明的作用。
/// Adds two numbers and returns the sum.
int add(int a, int b) => a + b;用一行摘要开头
请用一句简短的摘要句子开始每条文档注释。工具会在列表中首先显示这一行，因此请确保它清晰完整，即使单独阅读也能表达清楚。
支持 Markdown
文档注释支持 Markdown，因此您可以添加强调、列表和链接。几乎无需额外操作，您在 pub.dev 上的渲染页面就会显得十分专业。
/// Returns the **first** matching item.链接到其他符号
将名称放在方括号中即可创建可用的交叉链接。读者可以直接跳转到生成文档中的相关类或方法。
/// See [add] for the inverse of [subtract].在围栏代码块中加入代码示例
请在注释的围栏代码块中展示真实用法。简短的示例比大段文字更能快速教学，也能让用户确信代码确实可用。
记录每个公共成员
请尽量为每个公共类、函数和字段编写文档。私有的下划线成员可以不写说明，但任何导出的内容都值得用一句话介绍。
库级文档
在库指令上方添加文档注释，即可描述整个文件。这条库注释会成为该部分 API 的起始说明。
/// Math helpers for everyday use.
library calc;使用 dartdoc 生成网站
运行 dartdoc 工具，将您的注释转换为静态网站。发布时，pub.dev 会自动为您运行该工具。
dart doc .文档覆盖率可赢得评分
pub.dev 会奖励文档完善的软件包。更高的文档覆盖率会提升您的分数，并向选择依赖项的用户传达质量信号。⭐
让文档紧邻代码
由于文档注释位于代码旁边，因此很容易同步更新。请将过时的文档视为错误，并在行为发生变化时及时修复。
快速检查
Dart 将哪种注释形式视为文档注释？
回顾：可渲染的文档
现在您可以编写三斜线文档注释、链接符号、添加示例，并使用 dart 文档生成网站。清晰的文档更能赢得用户。🙌
常见问题解答
「使用 dartdoc 注释编写文档」课时是免费的吗？
是的 — 「使用 dartdoc 注释编写文档」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Dart Academy 课程的其余内容，请升级到 CoddyKit PRO。 Dart Academy 课程共包含 4 节课。
「使用 dartdoc 注释编写文档」这节课中我会学到什么？
编写可在 pub.dev 上呈现的文档 你通过在浏览器中直接运行的动手代码来练习 Dart Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。
学习 Dart Academy 需要有经验吗？
无需任何先前经验。CoddyKit 上的 Dart Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 2 节课，共 4 节。
「使用 dartdoc 注释编写文档」课时需要多长时间？
大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。
我能在这节 Dart Academy 课中编写并运行代码吗？
能。每节 Dart Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。
此课程中的所有课时
- 构建可发布的库
- 使用 dartdoc 注释编写文档
- 代码检查、格式化与 pana 评分
- 使用 dart pub publish 发布到 pub.dev