Contents

package_api_docs

Contents

Provide doc comments for all public APIs.

This rule is available as of Dart 2.0.

Details

#

DO provide doc comments for all public APIs.

As described in the pub package layout doc, public APIs consist in everything in your package's lib folder, minus implementation files in lib/src, adding elements explicitly exported with an export directive.

For example, given lib/foo.dart:

dart
export 'src/bar.dart' show Bar;
export 'src/baz.dart';

class Foo { }

class _Foo { }

its API includes:

  • Foo (but not _Foo)
  • Bar (exported) and
  • all public elements in src/baz.dart

All public API members should be documented with /// doc-style comments.

BAD:

dart
class Bar {
  void bar();
}

GOOD:

dart
/// A Foo.
abstract class Foo {
  /// Start foo-ing.
  void start() => _start();

  _start();
}

Advice for writing good doc comments can be found in the Doc Writing Guidelines.

Usage

#

To enable the package_api_docs rule, add package_api_docs under linter > rules in your analysis_options.yaml file:

analysis_options.yaml
yaml
linter:
  rules:
    - package_api_docs