package_api_docs

Provide doc comments for all public APIs.

NOTE: This lint has been removed because it is has not been fully functional since at least Dart 2.0. Remove all inclusions of this lint from your analysis options.

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:

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:

class Bar {
  void bar();
}

GOOD:

/// 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.

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

linter:
  rules:
    - package_api_docs

If you're instead using the YAML map syntax to configure linter rules, add package_api_docs: true under linter > rules:

linter:
  rules:
    package_api_docs: true