package_ api_ docs
Provide doc comments for all public APIs.
Details
#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.
Enable
#
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
Unless stated otherwise, the documentation on this site reflects Dart 3.9.2. Report an issue.