bafa71a8ae
Change-Id: I1c9592d4ce66d08aafacd5ae9722defa114c9953 Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/214867 Reviewed-by: Konstantin Shcheglov <scheglov@google.com> Commit-Queue: Devon Carew <devoncarew@google.com> |
||
---|---|---|
.. | ||
bin | ||
pubspec.yaml | ||
README.md |
Whats' this?
A tool to validate the documentation comments for the dart:
libraries.
Running the tool
To validate all the dart: libraries, run:
dart tools/verify_docs/bin/verify_docs.dart
Or to validate an individual library (async, collection, js_util, ...), run:
dart tools/verify_docs/bin/verify_docs.dart sdk/lib/<lib-name>
The tool should be run from the root of the sdk repository.
Authoring code samples
What gets analyzed
This tool will walk all dartdoc api docs looking for code samples in doc comments.
It will analyze any code sample in a dart
code fence. For example:
print('hello world!');
By default, an import for that library is added to the sample being analyzed (i.e.,
import 'dart:async";
). Additionally, the code sample is automatically embedded in
the body of a simple main() method.
Excluding code samples from analysis
In order to exclude a code sample from analysis, change it to a plain code fence style:
print("I'm not analyzed :(");
Specifying additional imports
In order to reference code from other Dart core libraries, you can either explicitly add the import to the code sample - in-line in the sample - or use a directive on the same line as the code fence. The directive style looks like:
print('hello world ${Timer()}');
Multiple imports can be specified like this if desired (i.e., "```dart import:async import:convert").