Update documentation according to Effective Dart documentation guide #664
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Effective Dart documentation section:
https://dart.dev/guides/language/effective-dart/documentation
This addresses reviews in cl/449413572 about the documentation in this library.
Summary of changes:
Use noun phrases in getters, fields
Replace
[:...:]
syntax with``
Use
[...]
syntax for in-scope identifiers in comments and documentationUse "create" instead of "return" for methods that create a new instance
(rather than returning an existing one)
Give a single sentence summary in API docs, move the rest to new paragraph(s)
When documentation exception behavior, start the sentence with "Throws" in a
new paragraph. Similarly when documenting return values do the same, starting
with "Returns".
Some rewording
Use
ArgumentError.value
constructor in some cases (instead ofArgumentError
)Note that I did not review every line of comment/doc in the library to update
them according to the Effective Dart guidelines. This only addresses reviews
that came up in cl/449413572.
@lrhn Could you review please? (GitHub doesn't let me add you as a reviewer)