dartdoc_test

Description:

dartdoc test

dartdoc_test #
This package provides an easy way to test code samples embedded in documentation comments.
Disclaimer: This is not an officially supported Google product.
Background #
Writing code samples in documentation comments is a great way to make your code easier to understand.
And code samples are seen many times in API Documentation and are often copied and used.
However, code samples in documentation comments are not analyzed, which makes them unreliable and difficult to maintain.
Most dart packages and libraries provide lots of documentation and code samples, and maintainability become a big issue.
Therefore, dartdoc_test provides a way to analyze code samples in documentation comments and detect problems they comtain. This improbes the maintainability and reliability of your documentation.
Using in cli #
# Add dartdoc_test as dev dependency
dart pub add dev:dartdoc_test

# Run dartdoc_test directly
dart run dartdoc_test
copied to clipboard
Using in test #
By creating test/dartdoc_test.dart, you can test code samples with using the dart test command.
# Add dartdoc_test as dev dependency
dart pub add dev:dartdoc_test

# Create test file for code samples to "test/dartdoc_test.dart"
dart run dartdoc_test add

# Run test command
dart test
copied to clipboard
The add command creates a test file like this:
import 'package:dartdoc_test/dartdoc_test.dart';

/// Test code samples in documentation comments in this package.
///
/// It extracts code samples from documentation comments in this package and
/// analyzes them. If there are any errors in the code samples, the test will fail
/// and you can see the problems details.
///
/// If you want to test only specific files, you can use [exclude] options.
void main() => runDartdocTest();
copied to clipboard
Ignore analysis #
If you don't want to analyze a particular code sample, you can exclude it by adding tag #no-test within the code block.
/// This code sample will not be analyzed.
///
/// ```dart#no-test
/// final a = 1 // it is not reported.
/// ```
copied to clipboard
Alternatively, if you want to exclude a particular directory or file, you can use the exclude option.
dart run dartdoc_test --exclude "example/**,*_test.dart"
copied to clipboard
Or
void main() {
runDartdocTest(
exclude: ['*_test.dart', 'example/**'],
);
}
copied to clipboard