package_api_docs
为所有公共 API 提供文档注释。
详情
#注意: 此 lint 已被移除,因为它至少自 Dart 2.0 以来一直没有完全发挥作用。从您的分析选项中删除所有包含此 lint 的内容。
务必为所有公共 API 提供文档注释。
正如 pub 包布局文档中所述,公共 API 包括您软件包的 lib
文件夹中的所有内容,减去 lib/src
中的实现文件,并添加使用 export
指令显式导出的元素。
例如,给定 lib/foo.dart
dart
export 'src/bar.dart' show Bar;
export 'src/baz.dart';
class Foo { }
class _Foo { }
其 API 包括
Foo
(但不包括_Foo
)Bar
(已导出) 和src/baz.dart
中的所有公共元素
所有公共 API 成员都应该使用 ///
doc-style 注释进行文档化。
错误
dart
class Bar {
void bar();
}
正确
dart
/// A Foo.
abstract class Foo {
/// Start foo-ing.
void start() => _start();
_start();
}
关于编写良好文档注释的建议可以在文档编写指南中找到。
启用
#要启用 package_api_docs
规则,请在您的 analysis_options.yaml
文件中的 linter > rules 下添加 package_api_docs
analysis_options.yaml
yaml
linter:
rules:
- package_api_docs
如果您改为使用 YAML 映射语法来配置 linter 规则,请在 linter > rules 下添加 package_api_docs: true
。
analysis_options.yaml
yaml
linter:
rules:
package_api_docs: true
除非另有说明,否则本网站上的文档反映了 Dart 3.7.1 版本。页面上次更新于 2025-03-07。 查看源代码 或 报告问题。