type_ annotate_ public_ apis
Type annotate public APIs.
Details
#From Effective Dart:
PREFER type annotating public APIs.
Type annotations are important documentation for how a library should be used. Annotating the parameter and return types of public methods and functions helps users understand what the API expects and what it provides.
Note that if a public API accepts a range of values that Dart's type system
cannot express, then it is acceptable to leave that untyped. In that case, the
implicit
dynamic
is the correct type for the API.
For code internal to a library (either private, or things like nested functions) annotate where you feel it helps, but don't feel that you must provide them.
BAD:
install(id, destination) {
// ...
}
Here, it's unclear what
id
is. A string? And what is
destination
? A string
or a
File
object? Is this method synchronous or asynchronous?
GOOD:
Future<bool> install(PackageId id, String destination) {
// ...
}
With types, all of this is clarified.
Incompatible rules
#The type_annotate_public_apis
lint is incompatible with the following rules:
Enable
#
To enable the
type_annotate_public_apis
rule, add
type_annotate_public_apis
under
linter > rules
in your
analysis_options.yaml
file:
linter:
rules:
- type_annotate_public_apis
If you're instead using the YAML map syntax to configure linter rules,
add
type_annotate_public_apis: true
under
linter > rules:
linter:
rules:
type_annotate_public_apis: true
Unless stated otherwise, the documentation on this site reflects Dart 3.9.2. Report an issue.