一个用于维护 **Da**rt **co**mments (daco) 的工具。
入门
-
请确保您已安装最新版本的 NodeJS (>=14) 并已将其添加到 PATH。daco 使用 prettier 来格式化 Markdown。
-
全局安装 daco
dart pub global activate daco
-
格式化当前目录下的 Dart 文件
daco format .
格式化
daco 格式化 Dart 文件中的文档注释。
prettier 用于将注释格式化为 Markdown。这意味着会应用 prettier 的约定，例如使用 ** 来加粗文本而不是 __。prettier 的一个优点是 Markdown 表格会被漂亮地格式化。
散文根据指定的行长度（默认为 80）进行重新排版以达到最佳效果
- /// The quick brown fox jumps over the lazy dog. The quick brown fox jumps over the lazy dog.+ /// The quick brown fox jumps over the lazy dog. The quick brown fox jumps over+ /// the lazy dog. const foo = 'bar';
这在编写和更新文档注释时非常有用，因为编辑可能会将一些文本推到首选行长度之外。
嵌入的 Dart 代码
用 dart 标记的围起来的代码块会被格式化为 Dart 代码。
/// A top level constant. /// /// ```dart- /// const fooList = [foo,];+ /// const fooList = [+ /// foo,+ /// ]; /// ``` const foo = 'bar';
Dart 代码会被解析，如果包含语法错误，将报告正确的行号和列号。这提供了对代码的基本检查，确保它至少在语法上是正确的。
如果代码不代表一个有效的 Dart 文件，可以通过标记 no_format 来禁用其格式化。
/// A top level constant.////// ```dart no_format/// print(foo)/// ```const foo = 'bar';
Dart 代码和文档注释的格式化是**递归**的。这意味着包含 Dart 代码的围起来的代码块中的注释也会被格式化。
Dartdoc 标签
Dartdoc 支持诸如模板等功能的标签。Dartdoc 标签应与内容之间留有空行，因为 prettier 不将其识别为特殊内容，而是将其格式化为纯文本。
/// A top level constant.////// {@template foo}////// The template content.////// {@endtemplate}const foo = 'bar';
在格式化现有代码库时，应特别注意 Dartdoc 标签在格式化后的位置。
待办事项
- 支持嵌入 Dart 代码中的独立语句
- 支持格式化行尾注释
- 支持禁用对注释的格式化
想法
- 与 IDE 集成格式化
- 分析注释
- 拼写
- 标点符号
- 格式化 Markdown 文件中的 Dart 代码
- 分析嵌入 Markdown 中的 Dart 代码
- 测试嵌入 Markdown 中的 Dart 代码
- 嵌入 Markdown 中的模板
- 模板被注释掉了
- 模板下方，模板的输出被注入/更新
• **Twitter**@GTerwesten • **Medium**@gabriel.terwesten
