Tested: CI validation Change-Id: If65cc156130a65ffe00c6f1660ac320e2921afae Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/246053 Commit-Queue: Devon Carew <devoncarew@google.com> Reviewed-by: Nate Bosch <nbosch@google.com>
3.9 KiB
What’s 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 either of:
dart tools/verify_docs/bin/verify_docs.dart sdk/lib/<lib-name>
dart tools/verify_docs/bin/verify_docs.dart dart:<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:
/// ```dart /// print('hello world!'); /// ```
By default, an import for that library is added to the sample being analyzed, e.g., import 'dart:async";
.
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 templates
The analysis tool can inject the code sample into a template before analyzing the sample. This allows the author to focus on the important parts of the API being documented with less boilerplate in the generated docs.
The template includes an automatic import of the library containing the example, so an example in, say, the documentation of StreamController.add
would have dart:async
imported automatically.
The tool will try and automatically detect the right template to use based on code patterns within the sample itself. In order to explicitly indicate which template to use, you can specify it as part of the code fence line. For example:
/// ```dart template:main /// print('hello world ${Timer()}'); /// ```
The current templates are:
none
: Do not wrap the code sample in any template, including no imports.top
: The code sample is top level code, preceded only by imports.main
: The code sample is one or more statements in a simple asynchronousmain()
function.expression
: The code sample is an expression within a simple asynchronousmain()
method.
For most code samples, the auto-detection code will select template:main
or
template:expression
.
If the example contains any library
declarations, the template becomes none
.
Specifying additional imports
If your example contains any library
, the default import of the current library is omitted. To avoid that, you can declare extra automatic imports in the code fence like:
/// ```dart import:async /// print('hello world ${Timer()}'); /// ```
Multiple imports can be specified like this if desired, e.g., " ```dart import:async import:convert
".
Does not work if combined with template:none
, whether the none
template is specified explicitly or auto-detected.
Splitting examples
Some examples may be split into separate code blocks, but should be seen as continuing the same running example.
If the following code blocks are marked as continued
as shown below, they
are included into the previous code block instead of being treated as a new
example.
/// ```dart /// var list = [1, 2, 3]; /// ``` /// And then you can also do the following: /// ```dart continued /// list.forEach(print); /// ```
A continued
code block cannot have any other flags in the fence.
Including additional code for analysis
You can declare code that should be included in the analysis but not shown in
the API docs by adding a comment "// Examples can assume:" to the file (usually
at the top of the file, after the imports), following by one or more
commented-out lines of code. That code is included verbatim in the analysis, at top-level after the automatic imports. Does not work with template:none
.
For example:
// Examples can assume:
// final BuildContext context;
// final String userAvatarUrl;