跳到主要内容

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