Adding a few more dartdoc flags,
needed to convert the bots to call "dart doc" rather than "dartdoc"
Change-Id: Id2cda151079dc4b279b0df8cf7ada364297adcb9
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/228920
Reviewed-by: Samuel Rawlins <srawlins@google.com>
Commit-Queue: Michael Thomsen <mit@google.com>
diff --git a/pkg/dartdev/lib/src/commands/doc.dart b/pkg/dartdev/lib/src/commands/doc.dart
index 6201a28..69826d4 100644
--- a/pkg/dartdev/lib/src/commands/doc.dart
+++ b/pkg/dartdev/lib/src/commands/doc.dart
@@ -38,6 +38,19 @@
negatable: false,
help: 'Display warnings for broken links.',
);
+ argParser.addFlag(
+ 'sdk-docs',
+ hide: true,
+ negatable: false,
+ help: 'Generate API docs for the Dart SDK.',
+ );
+ argParser.addFlag(
+ 'dry-run',
+ negatable: false,
+ help: 'Try to generate the docs without saving them.',
+ );
+ argParser.addFlag('fatal-warnings',
+ help: 'Treat warning level issues as fatal.', defaultsTo: false);
}
@override
@@ -45,28 +58,37 @@
@override
FutureOr<int> run() async {
- // At least one argument, the input directory, is required.
- if (argResults.rest.isEmpty) {
- usageException("Error: Input directory not specified");
- }
+ final options = <String>[];
- // Determine input directory.
- final dir = io.Directory(argResults.rest[0]);
- if (!dir.existsSync()) {
- usageException("Error: Input directory doesn't exist: ${dir.path}");
+ if (argResults['sdk-docs']) {
+ options.add('--sdk-docs');
+ } else {
+ // At least one argument, the input directory, is required,
+ // when we're not generating docs for the Dart SDK.
+ if (argResults.rest.isEmpty) {
+ usageException("Error: Input directory not specified");
+ }
+
+ // Determine input directory.
+ final dir = io.Directory(argResults.rest[0]);
+ if (!dir.existsSync()) {
+ usageException("Error: Input directory doesn't exist: ${dir.path}");
+ }
+ options.add('--input=${dir.path}');
}
// Specify where dartdoc resources are located.
final resourcesPath =
path.absolute(sdk.sdkPath, 'bin', 'resources', 'dartdoc', 'resources');
- // Build options.
- final options = [
- '--input=${dir.path}',
+ // Build remaining options.
+ options.addAll([
'--output=${argResults['output']}',
'--resources-dir=$resourcesPath',
- if (argResults['validate-links']) '--validate-links'
- ];
+ if (argResults['validate-links']) '--validate-links',
+ if (argResults['dry-run']) '--no-generate-docs',
+ if (verbose) '--no-quiet',
+ ]);
final config = await parseOptions(pubPackageMetaProvider, options);
if (config == null) {
diff --git a/pkg/dartdev/test/commands/doc_test.dart b/pkg/dartdev/test/commands/doc_test.dart
index 9f57108..42ee01b 100644
--- a/pkg/dartdev/test/commands/doc_test.dart
+++ b/pkg/dartdev/test/commands/doc_test.dart
@@ -9,13 +9,13 @@
const int compileErrorExitCode = 64;
void main() {
- group('doc', defineCompileTests, timeout: longTimeout);
+ group('doc', defineDocTests, timeout: longTimeout);
}
-void defineCompileTests() {
+void defineDocTests() {
test('Passing no args fails', () async {
final p = project();
- var result = await p.run(['doc']);
+ final result = await p.run(['doc']);
expect(result.stderr, contains('Input directory not specified'));
expect(result.exitCode, compileErrorExitCode);
});
@@ -27,44 +27,70 @@
result.stdout,
contains('Usage: dart doc [arguments] <input directory>'),
);
-
expect(result.exitCode, 0);
});
test('Document a library', () async {
- final source = '''
+ final p = project(mainSrc: 'void main() { print("Hello, World"); }');
+ p.file('lib/foo.dart', '''
/// This is Foo. It uses [Bar].
class Foo {
- Bar bar;
+ Bar bar;
}
/// Bar is very nice.
class Bar {
- _i = 42;
+ _i = 42;
}
- ''';
-
- final p = project(mainSrc: 'void main() { print("Hello, World"); }');
- p.file('lib/foo.dart', source);
+''');
final result = await p.run(['doc', '--validate-links', p.dirPath]);
- print(
- 'exit: ${result.exitCode}, stderr:\n${result.stderr}\nstdout:\n${result.stdout}');
expect(result.stdout, contains('Documenting dartdev_temp'));
+ expect(result.exitCode, 0);
+ });
+
+ test('Document a library dry-run', () async {
+ final p = project(mainSrc: 'void main() { print("Hello, World"); }');
+ p.file('lib/foo.dart', '''
+/// This is Foo.
+class Foo {
+ int i = 42;
+}
+''');
+ final result = await p.run(['doc', '--dry-run', '--verbose', p.dirPath]);
+ expect(result.stdout, contains('Documenting dartdev_temp'));
+ expect(result.exitCode, 0);
+ });
+
+ test('Errors cause error code', () async {
+ final p = project(mainSrc: 'void main() { print("Hello, World"); }');
+ p.file('lib/foo.dart', '''
+/// This is Foo. It uses [TypeThatIsntDeclared].
+class Foo {
+ int i = 42;
+}
+''');
+ p.file('dartdoc_options.yaml', '''
+dartdoc:
+ errors:
+ - unresolved-doc-reference
+''');
+ final result = await p.run(['doc', p.dirPath]);
+ expect(result.exitCode, 1);
});
test('Document a library with broken link is flagged', () async {
final source = '''
/// This is Foo. It uses [Baz].
class Foo {
- // Bar bar;
+ int i = 42;
}
- ''';
+''';
final p = project(mainSrc: 'void main() { print("Hello, World"); }');
p.file('lib/foo.dart', source);
final result = await p.run(['doc', '--validate-links', p.dirPath]);
- print(
- 'exit: ${result.exitCode}, stderr:\n${result.stderr}\nstdout:\n${result.stdout}');
+ // TODO (mit@): Update this test to actually test for the
+ // --validate-links flag.
expect(result.stdout, contains('Documenting dartdev_temp'));
});
}
