From 5c353583e0aafff8f6e8fc48e4e9b60054c4f5c6 Mon Sep 17 00:00:00 2001 From: takumma Date: Wed, 31 Jul 2024 00:53:20 +0900 Subject: [PATCH 01/23] implement code sample ignoring --- dartdoc_test/example/lib/example.dart | 9 +++++++++ dartdoc_test/lib/src/extractor.dart | 5 +++++ dartdoc_test/lib/src/resource.dart | 3 ++- 3 files changed, 16 insertions(+), 1 deletion(-) diff --git a/dartdoc_test/example/lib/example.dart b/dartdoc_test/example/lib/example.dart index 50e32f0a..a465e881 100644 --- a/dartdoc_test/example/lib/example.dart +++ b/dartdoc_test/example/lib/example.dart @@ -52,6 +52,15 @@ int multiply(int x, int y) { /// ``` void ignore() {} +/// you can ignore code sample by using `no-test` tag. +/// +/// ```dart +/// // dartdoc_test:ignore_error +/// final a = 0; +/// taG_ignore(); // it is not reported. +/// ``` +void tag_ignore() {} + /// Should return: Expected to find ';'. /// ```dart /// final fact = factorial(5) diff --git a/dartdoc_test/lib/src/extractor.dart b/dartdoc_test/lib/src/extractor.dart index 5034c88e..97fa9f57 100644 --- a/dartdoc_test/lib/src/extractor.dart +++ b/dartdoc_test/lib/src/extractor.dart @@ -56,6 +56,11 @@ class DocumentationCodeSample { this.imports = const [], }); + bool get ignore => code.contains('// dartdoc_test:ignore_error'); + + bool get hasMain => code.contains('void main()'); + bool get hasImport => code.contains('import '); + String wrappedCode(Directory testDir) { final fileName = comment.span.sourceUrl; diff --git a/dartdoc_test/lib/src/resource.dart b/dartdoc_test/lib/src/resource.dart index 045dac04..5334eab4 100644 --- a/dartdoc_test/lib/src/resource.dart +++ b/dartdoc_test/lib/src/resource.dart @@ -63,7 +63,8 @@ class DartdocTestContext { final _files = {}; - Set get codeSampleFiles => _files; + Set get codeSampleFiles => + _files.where((f) => !f.sample.ignore).toSet(); AnalysisContext get context => _context; void _writeFile(String path, DocumentationCodeSample sample) { From f83264556d3ceb4f6c0fc610b9a6180529a81076 Mon Sep 17 00:00:00 2001 From: takumma Date: Sun, 4 Aug 2024 16:06:49 +0900 Subject: [PATCH 02/23] add comments --- dartdoc_test/README.md | 2 ++ dartdoc_test/lib/dartdoc_test.dart | 8 +++++++- dartdoc_test/lib/src/command/add.dart | 18 +++++++++++++----- dartdoc_test/lib/src/extractor.dart | 15 ++++++++++++--- dartdoc_test/test/dartdoc_test.dart | 1 - 5 files changed, 34 insertions(+), 10 deletions(-) diff --git a/dartdoc_test/README.md b/dartdoc_test/README.md index 915c2382..41003e15 100644 --- a/dartdoc_test/README.md +++ b/dartdoc_test/README.md @@ -30,3 +30,5 @@ and then ```bash dart test ``` + +# Background diff --git a/dartdoc_test/lib/dartdoc_test.dart b/dartdoc_test/lib/dartdoc_test.dart index 303d31ef..5b5511bc 100644 --- a/dartdoc_test/lib/dartdoc_test.dart +++ b/dartdoc_test/lib/dartdoc_test.dart @@ -19,10 +19,16 @@ import 'src/logger.dart'; import 'src/reporter.dart'; import 'src/resource.dart'; -/// Test code samples in documentation comments. +/// Test code samples in documentation comments in this package. +/// +/// this function creates test cases that analyze code samples in documentation +/// and you can call this function in your test file and run it with `dart test`. +/// The easiest way to create a test file for code samples is to use the +/// command `dart run dartdoc_test:add`. /// /// In default, this function will test all code samples in your project. if you /// want to test only specific files, you can use [include] and [exclude] options. +/// and if you need more logs, you can set [verbose] to true. void runDartdocTest({ List include = const [], List exclude = const [], diff --git a/dartdoc_test/lib/src/command/add.dart b/dartdoc_test/lib/src/command/add.dart index 795f61b2..c4968793 100644 --- a/dartdoc_test/lib/src/command/add.dart +++ b/dartdoc_test/lib/src/command/add.dart @@ -24,7 +24,8 @@ class AddCommand extends DartdocTestCommand { String get name => 'add'; @override - String get description => 'Generate dartdoc_test test file.'; + String get description => + 'Add dartdoc_test test file "test/dartdoc_test.dart"'; AddCommand() { argParser.addFlag( @@ -36,20 +37,27 @@ class AddCommand extends DartdocTestCommand { @override Future run() async { - logger.info('Creating \'test/dartdoc_test.dart\' ...'); + logger.info('Creating "test/dartdoc_test.dart" ...'); final path = p.join(currentDir.path, 'test', 'dartdoc_test.dart'); final force = argResults.flag('force'); if (!force && File(path).existsSync()) { logger.info('\'test/dartdoc_test.dart\' is already exists.'); - logger.info('if you want to create forcely, use --force option.'); + logger.info('if you want to create file forcely, use --force option.'); return; } final content = ''' import 'package:dartdoc_test/dartdoc_test.dart'; -/// [runDartdocTest] is a test function that tests code samples. +/// 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 [include] and [exclude] +/// options. void main() => runDartdocTest(); '''; @@ -61,6 +69,6 @@ void main() => runDartdocTest(); final file = File(p.join(directory.path, 'dartdoc_test.dart')); await file.writeAsString(content); - logger.info('Done! Run \'dart test\' to analyze code samples.'); + logger.info('Done! You can run \'dart test\' to analyze code samples.'); } } diff --git a/dartdoc_test/lib/src/extractor.dart b/dartdoc_test/lib/src/extractor.dart index 97fa9f57..f9bdc725 100644 --- a/dartdoc_test/lib/src/extractor.dart +++ b/dartdoc_test/lib/src/extractor.dart @@ -24,6 +24,7 @@ import 'package:source_span/source_span.dart'; final _md = Document(extensionSet: ExtensionSet.gitHubWeb); +/// A documentation comment extracted from a source file. class DocumentationComment { /// The path of the original file final String path; @@ -45,22 +46,24 @@ class DocumentationComment { }); } +/// A code sample extracted from a documentation comment. class DocumentationCodeSample { + /// The documentation comment that contains the code sample. final DocumentationComment comment; + + /// content of the code sample. final String code; - final List imports; DocumentationCodeSample({ required this.comment, required this.code, - this.imports = const [], }); bool get ignore => code.contains('// dartdoc_test:ignore_error'); - bool get hasMain => code.contains('void main()'); bool get hasImport => code.contains('import '); + /// Create a sample by wrapping the code with a main function and imports. String wrappedCode(Directory testDir) { final fileName = comment.span.sourceUrl; @@ -118,6 +121,12 @@ List extractDocumentationComments(ParsedUnitResult r) { return comments; } +/// Strips leading whitespaces from a string. +/// +/// ```dart +/// final comment = ' /// some comment\n'; +/// print(stripleadingWhiteSpace(comment)); // ['/// some comment'] +/// ``` Iterable stripleadingWhiteSpace(String comment) { final lines = LineSplitter.split(comment); return lines.map((l) => l.trimLeft()); diff --git a/dartdoc_test/test/dartdoc_test.dart b/dartdoc_test/test/dartdoc_test.dart index c283ca6d..5e75d8ee 100644 --- a/dartdoc_test/test/dartdoc_test.dart +++ b/dartdoc_test/test/dartdoc_test.dart @@ -2,4 +2,3 @@ import 'package:dartdoc_test/dartdoc_test.dart'; /// [runDartdocTest] is a test function that tests code samples. void main() => runDartdocTest(); - From 9194c41986b7613608d54577bf29934443d5bf63 Mon Sep 17 00:00:00 2001 From: takumma Date: Sun, 4 Aug 2024 17:23:09 +0900 Subject: [PATCH 03/23] fix ignoring and test --- dartdoc_test/example/lib/example.dart | 6 +- dartdoc_test/lib/src/resource.dart | 4 + .../test/testdata/codeSample/example_4.dart | 4 +- .../test/testdata/codeSample/example_5.dart | 4 +- .../test/testdata/codeSample/example_6.dart | 4 +- .../{example_3.dart => example_7.dart} | 4 +- .../test/testdata/codeSample/extractor_0.dart | 4 +- .../test/testdata/codeSample/extractor_1.dart | 7 +- .../test/testdata/codeSample/extractor_2.dart | 17 ++++ dartdoc_test/test/testdata/dartdoc_test.txt | 28 ++++--- .../test/testdata/dartdoc_test_example.txt | 82 +++++++------------ ...e command by default with verbose flag.txt | 53 +++++++++--- .../run analyze command by default.txt | 14 ++-- .../run analyze command with verbose flag.txt | 53 +++++++++--- .../test/testdata/run analyze command.txt | 14 ++-- dartdoc_test/test/testdata/show help.txt | 2 +- 16 files changed, 183 insertions(+), 117 deletions(-) rename dartdoc_test/test/testdata/codeSample/{example_3.dart => example_7.dart} (50%) create mode 100644 dartdoc_test/test/testdata/codeSample/extractor_2.dart diff --git a/dartdoc_test/example/lib/example.dart b/dartdoc_test/example/lib/example.dart index a465e881..fc58163b 100644 --- a/dartdoc_test/example/lib/example.dart +++ b/dartdoc_test/example/lib/example.dart @@ -56,10 +56,10 @@ void ignore() {} /// /// ```dart /// // dartdoc_test:ignore_error -/// final a = 0; -/// taG_ignore(); // it is not reported. +/// +/// tagIgnore() // it is not reported. /// ``` -void tag_ignore() {} +void tagIgnore() {} /// Should return: Expected to find ';'. /// ```dart diff --git a/dartdoc_test/lib/src/resource.dart b/dartdoc_test/lib/src/resource.dart index 5334eab4..c4ff29fe 100644 --- a/dartdoc_test/lib/src/resource.dart +++ b/dartdoc_test/lib/src/resource.dart @@ -93,6 +93,10 @@ class DartdocTestContext { List samples, ) { for (final (i, s) in samples.indexed) { + if (s.ignore) { + continue; + } + final fileName = p.basename(filePath).replaceFirst('.dart', '_$i.dart'); final path = p.join(_testDir.path, fileName); _writeFile(path, s); diff --git a/dartdoc_test/test/testdata/codeSample/example_4.dart b/dartdoc_test/test/testdata/codeSample/example_4.dart index 587c5499..0c23ca45 100644 --- a/dartdoc_test/test/testdata/codeSample/example_4.dart +++ b/dartdoc_test/test/testdata/codeSample/example_4.dart @@ -2,6 +2,6 @@ import 'dart:convert'; import '../../../example/lib/example.dart'; void main() { - final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); - print(isPalindrome); // true + final fact = factorial(5) + print(fact); // 120 } diff --git a/dartdoc_test/test/testdata/codeSample/example_5.dart b/dartdoc_test/test/testdata/codeSample/example_5.dart index d562f5d7..587c5499 100644 --- a/dartdoc_test/test/testdata/codeSample/example_5.dart +++ b/dartdoc_test/test/testdata/codeSample/example_5.dart @@ -2,6 +2,6 @@ import 'dart:convert'; import '../../../example/lib/example.dart'; void main() { - final gcd = gcd(48, 18); - print(gcd); // 6 + final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); + print(isPalindrome); // true } diff --git a/dartdoc_test/test/testdata/codeSample/example_6.dart b/dartdoc_test/test/testdata/codeSample/example_6.dart index 67a4e066..d562f5d7 100644 --- a/dartdoc_test/test/testdata/codeSample/example_6.dart +++ b/dartdoc_test/test/testdata/codeSample/example_6.dart @@ -2,6 +2,6 @@ import 'dart:convert'; import '../../../example/lib/example.dart'; void main() { - final lines = splitLines('Hello\nWorld'); - print(lines); // ['Hello', 'World'] + final gcd = gcd(48, 18); + print(gcd); // 6 } diff --git a/dartdoc_test/test/testdata/codeSample/example_3.dart b/dartdoc_test/test/testdata/codeSample/example_7.dart similarity index 50% rename from dartdoc_test/test/testdata/codeSample/example_3.dart rename to dartdoc_test/test/testdata/codeSample/example_7.dart index 0c23ca45..67a4e066 100644 --- a/dartdoc_test/test/testdata/codeSample/example_3.dart +++ b/dartdoc_test/test/testdata/codeSample/example_7.dart @@ -2,6 +2,6 @@ import 'dart:convert'; import '../../../example/lib/example.dart'; void main() { - final fact = factorial(5) - print(fact); // 120 + final lines = splitLines('Hello\nWorld'); + print(lines); // ['Hello', 'World'] } diff --git a/dartdoc_test/test/testdata/codeSample/extractor_0.dart b/dartdoc_test/test/testdata/codeSample/extractor_0.dart index 9a486b68..4784c2a8 100644 --- a/dartdoc_test/test/testdata/codeSample/extractor_0.dart +++ b/dartdoc_test/test/testdata/codeSample/extractor_0.dart @@ -9,6 +9,6 @@ import 'package:source_span/source_span.dart'; import 'package:dartdoc_test/src/extractor.dart'; void main() { - final comment1 = '/// some comment'; - print(stripComments(comment1)); // 'some comment' + final comment = ' /// some comment\n'; + print(stripleadingWhiteSpace(comment)); // ['/// some comment'] } diff --git a/dartdoc_test/test/testdata/codeSample/extractor_1.dart b/dartdoc_test/test/testdata/codeSample/extractor_1.dart index 6d065e86..9a486b68 100644 --- a/dartdoc_test/test/testdata/codeSample/extractor_1.dart +++ b/dartdoc_test/test/testdata/codeSample/extractor_1.dart @@ -9,9 +9,6 @@ import 'package:source_span/source_span.dart'; import 'package:dartdoc_test/src/extractor.dart'; void main() { - final comment2 = ''' - /** - * some comment - */'''; - stripComments(comment2); // 'some comment' + final comment1 = '/// some comment'; + print(stripComments(comment1)); // 'some comment' } diff --git a/dartdoc_test/test/testdata/codeSample/extractor_2.dart b/dartdoc_test/test/testdata/codeSample/extractor_2.dart new file mode 100644 index 00000000..6d065e86 --- /dev/null +++ b/dartdoc_test/test/testdata/codeSample/extractor_2.dart @@ -0,0 +1,17 @@ +import 'dart:convert'; +import 'dart:io'; +import 'package:path/path.dart' as p; +import 'package:analyzer/dart/analysis/results.dart'; +import 'package:analyzer/dart/ast/ast.dart'; +import 'package:analyzer/dart/ast/visitor.dart'; +import 'package:markdown/markdown.dart'; +import 'package:source_span/source_span.dart'; +import 'package:dartdoc_test/src/extractor.dart'; + +void main() { + final comment2 = ''' + /** + * some comment + */'''; + stripComments(comment2); // 'some comment' +} diff --git a/dartdoc_test/test/testdata/dartdoc_test.txt b/dartdoc_test/test/testdata/dartdoc_test.txt index f736e7e2..d85b4846 100644 --- a/dartdoc_test/test/testdata/dartdoc_test.txt +++ b/dartdoc_test/test/testdata/dartdoc_test.txt @@ -6,36 +6,36 @@ Analyzing code samples ... 00:00 +2: [dartdoc_test] example/lib/example.dart test for null 00:00 +3: [dartdoc_test] example/lib/example.dart test for ) 00:00 +3 -1: [dartdoc_test] example/lib/example.dart test for ) [E] - example/lib/example.dart:57:29: : Expected to find ';'. + example/lib/example.dart:66:29: : Expected to find ';'. ╷ - 57 │ /// final fact = factorial(5) + 66 │ /// final fact = factorial(5) │ ^ ╵ package:matcher fail - package:dartdoc_test/src/reporter.dart 141:11 _RepoterForTest._reportIssue. + package:dartdoc_test/src/reporter.dart 140:11 _RepoterForTest._reportIssue. 00:00 +3 -1: [dartdoc_test] example/lib/example.dart test for null 00:00 +4 -1: [dartdoc_test] example/lib/example.dart test for isPalindrome 00:00 +4 -2: [dartdoc_test] example/lib/example.dart test for isPalindrome [E] - example/lib/example.dart:71:11: : Local variable 'isPalindrome' can't be referenced before it is declared. + example/lib/example.dart:80:11: : Local variable 'isPalindrome' can't be referenced before it is declared. ╷ - 71 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); + 80 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); │ ^^^^^^^^^^^^ ╵ package:matcher fail - package:dartdoc_test/src/reporter.dart 141:11 _RepoterForTest._reportIssue. + package:dartdoc_test/src/reporter.dart 140:11 _RepoterForTest._reportIssue. 00:00 +4 -2: [dartdoc_test] example/lib/example.dart test for null 00:00 +5 -2: [dartdoc_test] example/lib/example.dart test for null 00:00 +6 -2: [dartdoc_test] example/lib/example.dart test for gcd 00:00 +6 -3: [dartdoc_test] example/lib/example.dart test for gcd [E] - example/lib/example.dart:79:36: : Local variable 'gcd' can't be referenced before it is declared. + example/lib/example.dart:88:36: : Local variable 'gcd' can't be referenced before it is declared. ╷ - 79 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. + 88 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. │ ^^^ ╵ package:matcher fail - package:dartdoc_test/src/reporter.dart 141:11 _RepoterForTest._reportIssue. + package:dartdoc_test/src/reporter.dart 140:11 _RepoterForTest._reportIssue. 00:00 +6 -3: [dartdoc_test] example/lib/example.dart test for null 00:00 +7 -3: [dartdoc_test] example/lib/example.dart test for null @@ -56,7 +56,15 @@ Analyzing code samples ... 00:00 +22 -3: [dartdoc_test] lib/src/extractor.dart test for null 00:00 +23 -3: [dartdoc_test] lib/src/extractor.dart test for null 00:00 +24 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +25 -3: Some tests failed. +00:00 +25 -3: [dartdoc_test] lib/src/extractor.dart test for null +00:00 +26 -3: [dartdoc_test] lib/src/extractor.dart test for null +00:00 +27 -3: [dartdoc_test] lib/src/extractor.dart test for null +00:00 +28 -3: [dartdoc_test] lib/src/extractor.dart test for null +00:00 +29 -3: [dartdoc_test] lib/src/extractor.dart test for null +00:00 +30 -3: [dartdoc_test] lib/src/extractor.dart test for null +00:00 +31 -3: [dartdoc_test] lib/src/extractor.dart test for null +00:00 +32 -3: [dartdoc_test] lib/src/extractor.dart test for null +00:00 +33 -3: Some tests failed. Consider enabling the flag chain-stack-traces to receive more detailed exceptions. For example, 'dart test --chain-stack-traces'. diff --git a/dartdoc_test/test/testdata/dartdoc_test_example.txt b/dartdoc_test/test/testdata/dartdoc_test_example.txt index a159a4d5..52a18b03 100644 --- a/dartdoc_test/test/testdata/dartdoc_test_example.txt +++ b/dartdoc_test/test/testdata/dartdoc_test_example.txt @@ -1,72 +1,46 @@ 00:00 +0: loading test/dartdoc_test.dart Extracting code samples ... Analyzing code samples ... -00:00 +0: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for u -00:00 +0 -1: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for u [E] - package:example/example.dart:17:19: : Expected to find ';'. +00:00 +0: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null +00:00 +1: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null +00:00 +2: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null +00:00 +3: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for ) +00:00 +3 -1: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for ) [E] + package:example/example.dart:66:29: : Expected to find ';'. ╷ - 17 │ /// Example of documentation comments and code samples in Dart. - │ ^ + 66 │ /// final fact = factorial(5) + │ ^ ╵ package:matcher fail - package:dartdoc_test/src/reporter.dart 141:11 _RepoterForTest._reportIssue. + package:dartdoc_test/src/reporter.dart 140:11 _RepoterForTest._reportIssue. -00:00 +0 -1: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for add(2, 3); - -00:00 +0 -2: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for add(2, 3); - [E] - package:example/example.dart:21:20: : The function 'SimpleClass' isn't defined. - ╷ - 21 │ /// final result = add(2, 3); - │ ^^^^^^^^^^ - ╵ - package:matcher fail - package:dartdoc_test/src/reporter.dart 141:11 _RepoterForTest._reportIssue. - -00:00 +0 -2: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null -00:00 +1 -2: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null -00:00 +2 -2: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for ultiply(4, 5 -00:00 +2 -3: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for ultiply(4, 5 [E] - package:example/example.dart:30:21: : The function 'ComplexClass' isn't defined. - ╷ - 30 │ /// final result = multiply(4, 5); - │ ^^^^^^^^^^^^ - ╵ - package:matcher fail - package:dartdoc_test/src/reporter.dart 141:11 _RepoterForTest._reportIssue. - -00:00 +2 -3: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null -00:00 +3 -3: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null -00:00 +4 -3: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for = multiply(6 -00:00 +4 -4: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for = multiply(6 [E] - package:example/example.dart:35:18: : The function 'ComplexClass' isn't defined. +00:00 +3 -1: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null +00:00 +4 -1: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for isPalindrome +00:00 +4 -2: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for isPalindrome [E] + package:example/example.dart:80:11: : Local variable 'isPalindrome' can't be referenced before it is declared. ╷ - 35 │ /// final result = multiply(6, 7); - │ ^^^^^^^^^^^^ + 80 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); + │ ^^^^^^^^^^^^ ╵ package:matcher fail - package:dartdoc_test/src/reporter.dart 141:11 _RepoterForTest._reportIssue. + package:dartdoc_test/src/reporter.dart 140:11 _RepoterForTest._reportIssue. -00:00 +4 -4: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null -00:00 +5 -4: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null -00:00 +6 -4: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null -00:00 +7 -4: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null -00:00 +8 -4: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null -00:00 +9 -4: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for ndr -00:00 +9 -5: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for ndr [E] - package:example/example.dart:65:33: : Local variable 'gcd' can't be referenced before it is declared. +00:00 +4 -2: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null +00:00 +5 -2: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null +00:00 +6 -2: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for gcd +00:00 +6 -3: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for gcd [E] + package:example/example.dart:88:36: : Local variable 'gcd' can't be referenced before it is declared. ╷ - 65 │ /// Checks if a string is a palindrome. - │ ^^^ + 88 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. + │ ^^^ ╵ package:matcher fail - package:dartdoc_test/src/reporter.dart 141:11 _RepoterForTest._reportIssue. + package:dartdoc_test/src/reporter.dart 140:11 _RepoterForTest._reportIssue. -00:00 +9 -5: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null -00:00 +10 -5: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null -00:00 +11 -5: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null -00:00 +12 -5: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null -00:00 +13 -5: Some tests failed. +00:00 +6 -3: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null +00:00 +7 -3: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null +00:00 +8 -3: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null +00:00 +9 -3: Some tests failed. Consider enabling the flag chain-stack-traces to receive more detailed exceptions. For example, 'dart test --chain-stack-traces'. diff --git a/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt b/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt index 8f645723..d5aed189 100644 --- a/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt +++ b/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt @@ -1,25 +1,58 @@ $ dart run bin/dartdoc_test.dart -v Extracting code samples ... Analyzing code samples ... -original error: .dartdoc_test/example_3.dart:5:27: Expected to find ';'. -example/lib/example.dart:57:29: : Expected to find ';'. +.dartdoc_test/example_0.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/example_1.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/example_2.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +original error: .dartdoc_test/example_4.dart:5:27: Expected to find ';'. +example/lib/example.dart:66:29: : Expected to find ';'. ╷ -57 │ /// final fact = factorial(5) +66 │ /// final fact = factorial(5) │ ^ ╵ -original error: .dartdoc_test/example_4.dart:5:24: Local variable 'isPalindrome' can't be referenced before it is declared. -example/lib/example.dart:71:11: : Local variable 'isPalindrome' can't be referenced before it is declared. +.dartdoc_test/example_4.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +original error: .dartdoc_test/example_5.dart:5:24: Local variable 'isPalindrome' can't be referenced before it is declared. +example/lib/example.dart:80:11: : Local variable 'isPalindrome' can't be referenced before it is declared. ╷ -71 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); +80 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); │ ^^^^^^^^^^^^ ╵ -original error: .dartdoc_test/example_5.dart:5:15: Local variable 'gcd' can't be referenced before it is declared. -example/lib/example.dart:79:36: : Local variable 'gcd' can't be referenced before it is declared. +.dartdoc_test/example_5.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/example_5.dart:2:8: Unused import: '../example/lib/example.dart'. (ignored because issue occurs in the generated code) +original error: .dartdoc_test/example_6.dart:5:15: Local variable 'gcd' can't be referenced before it is declared. +example/lib/example.dart:88:36: : Local variable 'gcd' can't be referenced before it is declared. ╷ -79 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. +88 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. │ ^^^ ╵ -FAILED: 28 issues found (Found 11 code samples in 3 files) \ No newline at end of file +.dartdoc_test/example_6.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/example_6.dart:2:8: Unused import: '../example/lib/example.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/example_7.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_0.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_0.dart:2:8: Unused import: 'dart:io'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_0.dart:3:8: Unused import: 'package:path/path.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_0.dart:4:8: Unused import: 'package:analyzer/dart/analysis/results.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_0.dart:5:8: Unused import: 'package:analyzer/dart/ast/ast.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_0.dart:6:8: Unused import: 'package:analyzer/dart/ast/visitor.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_0.dart:7:8: Unused import: 'package:markdown/markdown.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_0.dart:8:8: Unused import: 'package:source_span/source_span.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_1.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_1.dart:2:8: Unused import: 'dart:io'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_1.dart:3:8: Unused import: 'package:path/path.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_1.dart:4:8: Unused import: 'package:analyzer/dart/analysis/results.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_1.dart:5:8: Unused import: 'package:analyzer/dart/ast/ast.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_1.dart:6:8: Unused import: 'package:analyzer/dart/ast/visitor.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_1.dart:7:8: Unused import: 'package:markdown/markdown.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_1.dart:8:8: Unused import: 'package:source_span/source_span.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_2.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_2.dart:2:8: Unused import: 'dart:io'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_2.dart:3:8: Unused import: 'package:path/path.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_2.dart:4:8: Unused import: 'package:analyzer/dart/analysis/results.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_2.dart:5:8: Unused import: 'package:analyzer/dart/ast/ast.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_2.dart:6:8: Unused import: 'package:analyzer/dart/ast/visitor.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_2.dart:7:8: Unused import: 'package:markdown/markdown.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_2.dart:8:8: Unused import: 'package:source_span/source_span.dart'. (ignored because issue occurs in the generated code) +FAILED: 36 issues found (Found 12 code samples in 3 files) \ No newline at end of file diff --git a/dartdoc_test/test/testdata/run analyze command by default.txt b/dartdoc_test/test/testdata/run analyze command by default.txt index df8b5e3a..d24a1556 100644 --- a/dartdoc_test/test/testdata/run analyze command by default.txt +++ b/dartdoc_test/test/testdata/run analyze command by default.txt @@ -1,22 +1,22 @@ $ dart run bin/dartdoc_test.dart Extracting code samples ... Analyzing code samples ... -example/lib/example.dart:57:29: : Expected to find ';'. +example/lib/example.dart:66:29: : Expected to find ';'. ╷ -57 │ /// final fact = factorial(5) +66 │ /// final fact = factorial(5) │ ^ ╵ -example/lib/example.dart:71:11: : Local variable 'isPalindrome' can't be referenced before it is declared. +example/lib/example.dart:80:11: : Local variable 'isPalindrome' can't be referenced before it is declared. ╷ -71 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); +80 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); │ ^^^^^^^^^^^^ ╵ -example/lib/example.dart:79:36: : Local variable 'gcd' can't be referenced before it is declared. +example/lib/example.dart:88:36: : Local variable 'gcd' can't be referenced before it is declared. ╷ -79 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. +88 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. │ ^^^ ╵ -FAILED: 28 issues found (Found 11 code samples in 3 files) \ No newline at end of file +FAILED: 36 issues found (Found 12 code samples in 3 files) \ No newline at end of file diff --git a/dartdoc_test/test/testdata/run analyze command with verbose flag.txt b/dartdoc_test/test/testdata/run analyze command with verbose flag.txt index 310db617..3bc610e8 100644 --- a/dartdoc_test/test/testdata/run analyze command with verbose flag.txt +++ b/dartdoc_test/test/testdata/run analyze command with verbose flag.txt @@ -1,25 +1,58 @@ $ dart run bin/dartdoc_test.dart analyze -v Extracting code samples ... Analyzing code samples ... -original error: .dartdoc_test/example_3.dart:5:27: Expected to find ';'. -example/lib/example.dart:57:29: : Expected to find ';'. +.dartdoc_test/example_0.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/example_1.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/example_2.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +original error: .dartdoc_test/example_4.dart:5:27: Expected to find ';'. +example/lib/example.dart:66:29: : Expected to find ';'. ╷ -57 │ /// final fact = factorial(5) +66 │ /// final fact = factorial(5) │ ^ ╵ -original error: .dartdoc_test/example_4.dart:5:24: Local variable 'isPalindrome' can't be referenced before it is declared. -example/lib/example.dart:71:11: : Local variable 'isPalindrome' can't be referenced before it is declared. +.dartdoc_test/example_4.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +original error: .dartdoc_test/example_5.dart:5:24: Local variable 'isPalindrome' can't be referenced before it is declared. +example/lib/example.dart:80:11: : Local variable 'isPalindrome' can't be referenced before it is declared. ╷ -71 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); +80 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); │ ^^^^^^^^^^^^ ╵ -original error: .dartdoc_test/example_5.dart:5:15: Local variable 'gcd' can't be referenced before it is declared. -example/lib/example.dart:79:36: : Local variable 'gcd' can't be referenced before it is declared. +.dartdoc_test/example_5.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/example_5.dart:2:8: Unused import: '../example/lib/example.dart'. (ignored because issue occurs in the generated code) +original error: .dartdoc_test/example_6.dart:5:15: Local variable 'gcd' can't be referenced before it is declared. +example/lib/example.dart:88:36: : Local variable 'gcd' can't be referenced before it is declared. ╷ -79 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. +88 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. │ ^^^ ╵ -FAILED: 28 issues found (Found 11 code samples in 3 files) \ No newline at end of file +.dartdoc_test/example_6.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/example_6.dart:2:8: Unused import: '../example/lib/example.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/example_7.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_0.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_0.dart:2:8: Unused import: 'dart:io'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_0.dart:3:8: Unused import: 'package:path/path.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_0.dart:4:8: Unused import: 'package:analyzer/dart/analysis/results.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_0.dart:5:8: Unused import: 'package:analyzer/dart/ast/ast.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_0.dart:6:8: Unused import: 'package:analyzer/dart/ast/visitor.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_0.dart:7:8: Unused import: 'package:markdown/markdown.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_0.dart:8:8: Unused import: 'package:source_span/source_span.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_1.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_1.dart:2:8: Unused import: 'dart:io'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_1.dart:3:8: Unused import: 'package:path/path.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_1.dart:4:8: Unused import: 'package:analyzer/dart/analysis/results.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_1.dart:5:8: Unused import: 'package:analyzer/dart/ast/ast.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_1.dart:6:8: Unused import: 'package:analyzer/dart/ast/visitor.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_1.dart:7:8: Unused import: 'package:markdown/markdown.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_1.dart:8:8: Unused import: 'package:source_span/source_span.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_2.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_2.dart:2:8: Unused import: 'dart:io'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_2.dart:3:8: Unused import: 'package:path/path.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_2.dart:4:8: Unused import: 'package:analyzer/dart/analysis/results.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_2.dart:5:8: Unused import: 'package:analyzer/dart/ast/ast.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_2.dart:6:8: Unused import: 'package:analyzer/dart/ast/visitor.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_2.dart:7:8: Unused import: 'package:markdown/markdown.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/extractor_2.dart:8:8: Unused import: 'package:source_span/source_span.dart'. (ignored because issue occurs in the generated code) +FAILED: 36 issues found (Found 12 code samples in 3 files) \ No newline at end of file diff --git a/dartdoc_test/test/testdata/run analyze command.txt b/dartdoc_test/test/testdata/run analyze command.txt index 51d01135..20733a3d 100644 --- a/dartdoc_test/test/testdata/run analyze command.txt +++ b/dartdoc_test/test/testdata/run analyze command.txt @@ -1,22 +1,22 @@ $ dart run bin/dartdoc_test.dart analyze Extracting code samples ... Analyzing code samples ... -example/lib/example.dart:57:29: : Expected to find ';'. +example/lib/example.dart:66:29: : Expected to find ';'. ╷ -57 │ /// final fact = factorial(5) +66 │ /// final fact = factorial(5) │ ^ ╵ -example/lib/example.dart:71:11: : Local variable 'isPalindrome' can't be referenced before it is declared. +example/lib/example.dart:80:11: : Local variable 'isPalindrome' can't be referenced before it is declared. ╷ -71 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); +80 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); │ ^^^^^^^^^^^^ ╵ -example/lib/example.dart:79:36: : Local variable 'gcd' can't be referenced before it is declared. +example/lib/example.dart:88:36: : Local variable 'gcd' can't be referenced before it is declared. ╷ -79 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. +88 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. │ ^^^ ╵ -FAILED: 28 issues found (Found 11 code samples in 3 files) \ No newline at end of file +FAILED: 36 issues found (Found 12 code samples in 3 files) \ No newline at end of file diff --git a/dartdoc_test/test/testdata/show help.txt b/dartdoc_test/test/testdata/show help.txt index 7cac2062..8716379d 100644 --- a/dartdoc_test/test/testdata/show help.txt +++ b/dartdoc_test/test/testdata/show help.txt @@ -8,7 +8,7 @@ Global options: -v, --[no-]verbose Print verbose output Available commands: - add Generate dartdoc_test test file. + add Add dartdoc_test test file "test/dartdoc_test.dart" analyze Analyze code samples in the current directory. Run "dartdoc_test help " for more information about a command. \ No newline at end of file From f71063f5835071d50a2fd4ea167a27d8b7957b5e Mon Sep 17 00:00:00 2001 From: takumma Date: Sun, 4 Aug 2024 23:53:12 +0900 Subject: [PATCH 04/23] update documentations --- dartdoc_test/README.md | 39 ++++++++++++++----- dartdoc_test/example/test/dartdoc_test.dart | 10 ++++- dartdoc_test/lib/dartdoc_test.dart | 9 +++-- dartdoc_test/lib/src/command/add.dart | 6 +-- dartdoc_test/lib/src/command/analyze.dart | 17 ++++++-- .../lib/src/command/command_runner.dart | 2 +- dartdoc_test/test/dartdoc_test.dart | 9 ++++- 7 files changed, 69 insertions(+), 23 deletions(-) diff --git a/dartdoc_test/README.md b/dartdoc_test/README.md index 41003e15..f7345241 100644 --- a/dartdoc_test/README.md +++ b/dartdoc_test/README.md @@ -1,10 +1,18 @@ # dartdoc_test -This package provides an easy way to test code samples embedded in dartdoc -documentation comments. +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 ```bash @@ -17,18 +25,29 @@ dart run dartdoc_test analyze # Using in test -You can test documentation code samples by creating `test/dartdoc_test.dart`. +By creating `test/dartdoc_test.dart`, you can test code samples with using the `dart test` command. + +```bash +# Create test file for code samples to "test/dartdoc_test.dart" +dart run dartdoc_test add + +# Run test command +dart test +``` + +The add command creates a test file like this: ```dart 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 [include] and [exclude] +/// options. void main() => runDartdocTest(); -``` - -and then -```bash -dart test ``` - -# Background diff --git a/dartdoc_test/example/test/dartdoc_test.dart b/dartdoc_test/example/test/dartdoc_test.dart index ee1fb734..cefeef4a 100644 --- a/dartdoc_test/example/test/dartdoc_test.dart +++ b/dartdoc_test/example/test/dartdoc_test.dart @@ -11,8 +11,14 @@ // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. - import 'package:dartdoc_test/dartdoc_test.dart'; -/// [runDartdocTest] is a test function that tests code samples. +/// 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 [include] and [exclude] +/// options. void main() => runDartdocTest(); diff --git a/dartdoc_test/lib/dartdoc_test.dart b/dartdoc_test/lib/dartdoc_test.dart index 5b5511bc..d254f7c1 100644 --- a/dartdoc_test/lib/dartdoc_test.dart +++ b/dartdoc_test/lib/dartdoc_test.dart @@ -24,7 +24,7 @@ import 'src/resource.dart'; /// this function creates test cases that analyze code samples in documentation /// and you can call this function in your test file and run it with `dart test`. /// The easiest way to create a test file for code samples is to use the -/// command `dart run dartdoc_test:add`. +/// command `dart run dartdoc_test add`. /// /// In default, this function will test all code samples in your project. if you /// want to test only specific files, you can use [include] and [exclude] options. @@ -34,8 +34,11 @@ void runDartdocTest({ List exclude = const [], bool verbose = false, }) async { - final options = - DartdocTestOptions(include: include, exclude: exclude, verbose: verbose); + final options = DartdocTestOptions( + include: include, + exclude: exclude, + verbose: verbose, + ); final dartdocTest = DartdocTest(options); final logger = Logger((message, level) { diff --git a/dartdoc_test/lib/src/command/add.dart b/dartdoc_test/lib/src/command/add.dart index c4968793..c2bfa9be 100644 --- a/dartdoc_test/lib/src/command/add.dart +++ b/dartdoc_test/lib/src/command/add.dart @@ -25,7 +25,7 @@ class AddCommand extends DartdocTestCommand { @override String get description => - 'Add dartdoc_test test file "test/dartdoc_test.dart"'; + 'Add dartdoc_test test file to "test/dartdoc_test.dart"'; AddCommand() { argParser.addFlag( @@ -42,7 +42,7 @@ class AddCommand extends DartdocTestCommand { final path = p.join(currentDir.path, 'test', 'dartdoc_test.dart'); final force = argResults.flag('force'); if (!force && File(path).existsSync()) { - logger.info('\'test/dartdoc_test.dart\' is already exists.'); + logger.info('"test/dartdoc_test.dart" is already exists.'); logger.info('if you want to create file forcely, use --force option.'); return; } @@ -69,6 +69,6 @@ void main() => runDartdocTest(); final file = File(p.join(directory.path, 'dartdoc_test.dart')); await file.writeAsString(content); - logger.info('Done! You can run \'dart test\' to analyze code samples.'); + logger.info('Done! You can run "dart test" to analyze code samples.'); } } diff --git a/dartdoc_test/lib/src/command/analyze.dart b/dartdoc_test/lib/src/command/analyze.dart index d44ededa..ab2c0462 100644 --- a/dartdoc_test/lib/src/command/analyze.dart +++ b/dartdoc_test/lib/src/command/analyze.dart @@ -27,19 +27,28 @@ class AnalyzeCommand extends DartdocTestCommand { String get name => 'analyze'; @override - String get description => 'Analyze code samples in the current directory.'; + String get description => + 'Analyze code samples in documentation comments in this project.'; AnalyzeCommand() { argParser ..addFlag( 'write', abbr: 'w', - help: 'Write code samples to file.', + help: 'Write code samples to physical files.', ) ..addOption( 'output', abbr: 'o', - help: 'Output code samples to file', + help: 'Directory to write code samples.', + ) + ..addMultiOption( + 'include', + help: 'Directories or files to analysis.', + ) + ..addMultiOption( + 'exclude', + help: 'Directories or files to exclude from analysis.', ); } @@ -49,6 +58,8 @@ class AnalyzeCommand extends DartdocTestCommand { write: argResults.flag('write'), verbose: globalResults.flag('verbose'), out: argResults.option('output'), + include: argResults.multiOption('include'), + exclude: argResults.multiOption('exclude'), )); logger.info('Extracting code samples ...'); await dartdocTest.extract(); diff --git a/dartdoc_test/lib/src/command/command_runner.dart b/dartdoc_test/lib/src/command/command_runner.dart index 4c94b015..88baea45 100644 --- a/dartdoc_test/lib/src/command/command_runner.dart +++ b/dartdoc_test/lib/src/command/command_runner.dart @@ -31,7 +31,7 @@ final class DartdocTestCommandRunner extends CommandRunner { argParser.addFlag( 'verbose', abbr: 'v', - help: 'Print verbose output', + help: 'Print detailed logging.', ); addCommand(AnalyzeCommand()); diff --git a/dartdoc_test/test/dartdoc_test.dart b/dartdoc_test/test/dartdoc_test.dart index 5e75d8ee..e2eb3934 100644 --- a/dartdoc_test/test/dartdoc_test.dart +++ b/dartdoc_test/test/dartdoc_test.dart @@ -1,4 +1,11 @@ import 'package:dartdoc_test/dartdoc_test.dart'; -/// [runDartdocTest] is a test function that tests code samples. +/// 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 [include] and [exclude] +/// options. void main() => runDartdocTest(); From 2e498d916024922272c69369e6500dbde28a459b Mon Sep 17 00:00:00 2001 From: takumma Date: Mon, 5 Aug 2024 13:23:51 +0900 Subject: [PATCH 05/23] add exclude option --- dartdoc_test/lib/dartdoc_test.dart | 5 +--- dartdoc_test/lib/src/command/analyze.dart | 22 ++---------------- dartdoc_test/lib/src/dartdoc_test.dart | 17 ++++++++------ dartdoc_test/lib/src/resource.dart | 23 +++++++++++-------- dartdoc_test/pubspec.yaml | 1 + dartdoc_test/test/integration_test.dart | 2 ++ ...un analyze command with exclude option.txt | 22 ++++++++++++++++++ dartdoc_test/test/testdata/show help.txt | 6 ++--- 8 files changed, 55 insertions(+), 43 deletions(-) create mode 100644 dartdoc_test/test/testdata/run analyze command with exclude option.txt diff --git a/dartdoc_test/lib/dartdoc_test.dart b/dartdoc_test/lib/dartdoc_test.dart index d254f7c1..e4c0f803 100644 --- a/dartdoc_test/lib/dartdoc_test.dart +++ b/dartdoc_test/lib/dartdoc_test.dart @@ -17,7 +17,6 @@ import 'dart:io'; import 'src/dartdoc_test.dart' show DartdocTest, DartdocTestOptions; import 'src/logger.dart'; import 'src/reporter.dart'; -import 'src/resource.dart'; /// Test code samples in documentation comments in this package. /// @@ -30,12 +29,10 @@ import 'src/resource.dart'; /// want to test only specific files, you can use [include] and [exclude] options. /// and if you need more logs, you can set [verbose] to true. void runDartdocTest({ - List include = const [], List exclude = const [], bool verbose = false, }) async { final options = DartdocTestOptions( - include: include, exclude: exclude, verbose: verbose, ); @@ -64,7 +61,7 @@ void runDartdocTest({ )); } } - final files = getFilesFrom(currentDir); + final files = dartdocTest.getFiles(); for (final file in files) { reporter.reportSourceFile(file.path); } diff --git a/dartdoc_test/lib/src/command/analyze.dart b/dartdoc_test/lib/src/command/analyze.dart index ab2c0462..40dc86c2 100644 --- a/dartdoc_test/lib/src/command/analyze.dart +++ b/dartdoc_test/lib/src/command/analyze.dart @@ -13,10 +13,6 @@ // limitations under the License. import 'package:dartdoc_test/src/reporter.dart'; -import 'package:dartdoc_test/src/resource.dart'; -import 'package:path/path.dart' as p; - -import 'package:source_span/source_span.dart'; import '../dartdoc_test.dart'; import '../logger.dart'; @@ -42,12 +38,9 @@ class AnalyzeCommand extends DartdocTestCommand { abbr: 'o', help: 'Directory to write code samples.', ) - ..addMultiOption( - 'include', - help: 'Directories or files to analysis.', - ) ..addMultiOption( 'exclude', + abbr: 'x', help: 'Directories or files to exclude from analysis.', ); } @@ -58,7 +51,6 @@ class AnalyzeCommand extends DartdocTestCommand { write: argResults.flag('write'), verbose: globalResults.flag('verbose'), out: argResults.option('output'), - include: argResults.multiOption('include'), exclude: argResults.multiOption('exclude'), )); logger.info('Extracting code samples ...'); @@ -83,20 +75,10 @@ class AnalyzeCommand extends DartdocTestCommand { logger.info('No issues found.'); } - final files = getFilesFrom(currentDir); + final files = dartdocTest.getFiles(); for (final file in files) { reporter.reportSourceFile(file.path); } logger.info(Summary.from(result).toString()); } } - -extension on FileSpan { - String format(String message) { - StringBuffer buffer = StringBuffer(); - buffer.write(p.prettyUri(sourceUrl)); - buffer.write(':${start.line + 1}:${(start.column + 1)}: '); - buffer.write(message); - return buffer.toString(); - } -} diff --git a/dartdoc_test/lib/src/dartdoc_test.dart b/dartdoc_test/lib/src/dartdoc_test.dart index 00f06339..3dbb7729 100644 --- a/dartdoc_test/lib/src/dartdoc_test.dart +++ b/dartdoc_test/lib/src/dartdoc_test.dart @@ -12,9 +12,12 @@ // See the License for the specific language governing permissions and // limitations under the License. +import 'dart:io'; + import 'package:args/args.dart'; import 'package:analyzer/dart/analysis/results.dart'; +import 'package:glob/glob.dart'; import 'analyzer.dart'; import 'extractor.dart'; @@ -29,7 +32,7 @@ class DartdocTest { /// Extract code samples from the currrent directory. Future extract() async { final session = _testContext.context.currentSession; - for (final file in getFilesFrom(currentDir)) { + for (final file in getFiles()) { final result = session.getParsedUnit(file.path); if (result is ParsedUnitResult) { @@ -51,22 +54,22 @@ class DartdocTest { return results; } + + List getFiles() => _testContext.getFiles(); } class DartdocTestOptions { final bool write; final bool verbose; - final List include; - final List exclude; + final List exclude; final String? out; - const DartdocTestOptions({ + DartdocTestOptions({ this.write = false, this.verbose = false, - this.include = const [], - this.exclude = const [], + List exclude = const [], this.out, - }); + }) : exclude = exclude.map((e) => Glob(e)).toList(); factory DartdocTestOptions.fromArg([ArgResults? args]) { if (args == null || args.arguments.isEmpty) { diff --git a/dartdoc_test/lib/src/resource.dart b/dartdoc_test/lib/src/resource.dart index c4ff29fe..65664d2e 100644 --- a/dartdoc_test/lib/src/resource.dart +++ b/dartdoc_test/lib/src/resource.dart @@ -102,16 +102,21 @@ class DartdocTestContext { _writeFile(path, s); } } -} -List getFilesFrom(Directory dir) { - // TODO: add `include` and `exclude` options - final files = dir - .listSync(recursive: true) - .whereType() - .where((file) => file.path.endsWith('.dart')) - .toList(); - return files; + bool _exclude(File file) { + final path = p.relative(file.path); + return !options.exclude.any((glob) => glob.matches(path)); + } + + List getFiles() { + final files = currentDir + .listSync(recursive: true) + .whereType() + .where((f) => f.path.endsWith('.dart')) + .where(_exclude) + .toList(); + return files; + } } class CodeSampleFile { diff --git a/dartdoc_test/pubspec.yaml b/dartdoc_test/pubspec.yaml index 83d2546f..6d4212aa 100644 --- a/dartdoc_test/pubspec.yaml +++ b/dartdoc_test/pubspec.yaml @@ -18,3 +18,4 @@ dependencies: markdown: ^7.0.2 path: ^1.8.3 source_span: ^1.10.0 + glob: ^2.1.2 diff --git a/dartdoc_test/test/integration_test.dart b/dartdoc_test/test/integration_test.dart index 9830d5e1..9e224ab7 100644 --- a/dartdoc_test/test/integration_test.dart +++ b/dartdoc_test/test/integration_test.dart @@ -24,6 +24,8 @@ void main() { testWithGolden('run analyze command by default', ['']); testWithGolden('run analyze command by default with verbose flag', ['-v']); testWithGolden('run analyze command with verbose flag', ['analyze', '-v']); + testWithGolden( + 'run analyze command with exclude option', ['analyze', '-x', 'lib/**']); group('extractor', () { test('extract code samples in example directory', () async { diff --git a/dartdoc_test/test/testdata/run analyze command with exclude option.txt b/dartdoc_test/test/testdata/run analyze command with exclude option.txt new file mode 100644 index 00000000..bf6627e3 --- /dev/null +++ b/dartdoc_test/test/testdata/run analyze command with exclude option.txt @@ -0,0 +1,22 @@ +$ dart run bin/dartdoc_test.dart analyze -x lib/** +Extracting code samples ... +Analyzing code samples ... +example/lib/example.dart:66:29: : Expected to find ';'. + ╷ +66 │ /// final fact = factorial(5) + │ ^ + ╵ + +example/lib/example.dart:80:11: : Local variable 'isPalindrome' can't be referenced before it is declared. + ╷ +80 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); + │ ^^^^^^^^^^^^ + ╵ + +example/lib/example.dart:88:36: : Local variable 'gcd' can't be referenced before it is declared. + ╷ +88 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. + │ ^^^ + ╵ + +FAILED: 12 issues found (Found 9 code samples in 2 files) \ No newline at end of file diff --git a/dartdoc_test/test/testdata/show help.txt b/dartdoc_test/test/testdata/show help.txt index 8716379d..78fbd7a2 100644 --- a/dartdoc_test/test/testdata/show help.txt +++ b/dartdoc_test/test/testdata/show help.txt @@ -5,10 +5,10 @@ Usage: dartdoc_test [arguments] Global options: -h, --help Print this usage information. --v, --[no-]verbose Print verbose output +-v, --[no-]verbose Print detailed logging. Available commands: - add Add dartdoc_test test file "test/dartdoc_test.dart" - analyze Analyze code samples in the current directory. + add Add dartdoc_test test file to "test/dartdoc_test.dart" + analyze Analyze code samples in documentation comments in this project. Run "dartdoc_test help " for more information about a command. \ No newline at end of file From 8e70be7563cc8a5424ce85d8a26253e4dcdbc326 Mon Sep 17 00:00:00 2001 From: takumma Date: Mon, 5 Aug 2024 19:51:52 +0900 Subject: [PATCH 06/23] fix summary and make ReporterForTest use verbose flag --- dartdoc_test/README.md | 33 +++++++- dartdoc_test/example/lib/error_example.dart | 58 ++++++++++++++ dartdoc_test/example/lib/example.dart | 73 +++++------------- dartdoc_test/example/lib/main.dart | 33 -------- dartdoc_test/example/test/dartdoc_test.dart | 3 +- dartdoc_test/lib/dartdoc_test.dart | 2 +- dartdoc_test/lib/src/command/add.dart | 3 +- dartdoc_test/lib/src/logger.dart | 2 +- dartdoc_test/lib/src/reporter.dart | 19 ++--- dartdoc_test/test/dartdoc_test.dart | 9 +-- .../testdata/codeSample/error_example_0.dart | 7 ++ .../{example_5.dart => error_example_1.dart} | 4 +- .../testdata/codeSample/error_example_2.dart | 7 ++ .../testdata/codeSample/error_example_3.dart | 7 ++ .../test/testdata/codeSample/example_1.dart | 4 +- .../test/testdata/codeSample/example_2.dart | 4 +- .../{example_4.dart => example_3.dart} | 4 +- .../test/testdata/codeSample/example_6.dart | 7 -- .../test/testdata/codeSample/example_7.dart | 7 -- .../test/testdata/codeSample/main_0.dart | 6 -- .../test/testdata/codeSample/main_1.dart | 6 -- dartdoc_test/test/testdata/dartdoc_test.txt | 75 +++++++------------ .../test/testdata/dartdoc_test_example.txt | 51 ++++++------- ...e command by default with verbose flag.txt | 43 ++++++----- .../run analyze command by default.txt | 20 +++-- ...un analyze command with exclude option.txt | 20 +++-- .../run analyze command with verbose flag.txt | 43 ++++++----- .../test/testdata/run analyze command.txt | 20 +++-- 28 files changed, 292 insertions(+), 278 deletions(-) create mode 100644 dartdoc_test/example/lib/error_example.dart delete mode 100644 dartdoc_test/example/lib/main.dart create mode 100644 dartdoc_test/test/testdata/codeSample/error_example_0.dart rename dartdoc_test/test/testdata/codeSample/{example_5.dart => error_example_1.dart} (63%) create mode 100644 dartdoc_test/test/testdata/codeSample/error_example_2.dart create mode 100644 dartdoc_test/test/testdata/codeSample/error_example_3.dart rename dartdoc_test/test/testdata/codeSample/{example_4.dart => example_3.dart} (60%) delete mode 100644 dartdoc_test/test/testdata/codeSample/example_6.dart delete mode 100644 dartdoc_test/test/testdata/codeSample/example_7.dart delete mode 100644 dartdoc_test/test/testdata/codeSample/main_0.dart delete mode 100644 dartdoc_test/test/testdata/codeSample/main_1.dart diff --git a/dartdoc_test/README.md b/dartdoc_test/README.md index f7345241..818a8ec9 100644 --- a/dartdoc_test/README.md +++ b/dartdoc_test/README.md @@ -46,8 +46,37 @@ import 'package:dartdoc_test/dartdoc_test.dart'; /// 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 [include] and [exclude] -/// options. +/// If you want to test only specific files, you can use [exclude] options. void main() => runDartdocTest(); ``` + +# Ignore analysis + +If you don't want to analyze a particular code sample, you can exclude it by adding an `// dartdoc_test:ignore_error` comment within the code sample. + +```` +/// This code sample will not be analyzed. +/// +/// ```dart +/// // dartdoc_test:ignore_error +/// +/// tagIgnore() // it is not reported. +/// ``` +```` + +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" +``` + +Or + +```dart +void main() { + runDartdocTest( + exclude: ['*_test.dart', 'example/**'], + ); +} +``` diff --git a/dartdoc_test/example/lib/error_example.dart b/dartdoc_test/example/lib/error_example.dart new file mode 100644 index 00000000..79953bb5 --- /dev/null +++ b/dartdoc_test/example/lib/error_example.dart @@ -0,0 +1,58 @@ +// Copyright 2023 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// https://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +/// Should return: Expected to find ';'. +/// ```dart +/// final fact = factorial(5) +/// print(fact); // 120 +/// ``` +int factorial(int n) { + if (n < 0) throw ArgumentError('Negative numbers are not allowed.'); + return n == 0 ? 1 : n * factorial(n - 1); +} + +/// Checks if a string is a palindrome. +/// +/// This method ignores case and non-alphanumeric characters. +/// +/// Example: +/// ```dart +/// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); +/// print(isPalindrome); // true +/// ``` +bool isPalindrome(String s) { + var sanitized = s.replaceAll(RegExp(r'[^A-Za-z0-9]'), '').toLowerCase(); + return sanitized == sanitized.split('').reversed.join(''); +} + +/// Should return: Local variable 'gcd' can't be referenced before it is declared. +/// ```dart +/// final gcd = gcd(48, 18); +/// print(gcd); // 6 +/// ``` +int gcd(int a, int b) { + while (b != 0) { + var t = b; + b = a % b; + a = t; + } + return a; +} + +/// Should return: The getter 'length' isn't defined for the class 'int'. +/// ```dart +/// final length = 5.length; +/// print(length); // 1 +/// ``` +void length() {} diff --git a/dartdoc_test/example/lib/example.dart b/dartdoc_test/example/lib/example.dart index fc58163b..b90ed26c 100644 --- a/dartdoc_test/example/lib/example.dart +++ b/dartdoc_test/example/lib/example.dart @@ -16,8 +16,9 @@ import 'dart:convert'; /// Example of documentation comments and code samples in Dart. -/// code block without specified language -/// ``` +/// Dart code block will be analyzed by dartdoc_test. +/// +/// ```dart /// final result = add(2, 3); /// print(result); // 5 /// ``` @@ -25,7 +26,18 @@ int add(int a, int b) { return a + b; } -/// multiple code blocks +/// If you don't specify the language for code blocks, it still be analyzed. +/// +/// ``` +/// final result = subtract(5, 3); +/// print(result); // 2 +/// ``` +int subtract(int x, int y) { + return x - y; +} + +/// Multiple code blocks are also analyzed. +/// /// ```dart /// final result = multiply(4, 5); /// print(result); // 20 @@ -39,7 +51,7 @@ int multiply(int x, int y) { return x * y; } -/// non-dart code block will be ignored. +/// Non-Dart code blocks are ignored. /// /// ```python /// def add(a, b): @@ -52,7 +64,7 @@ int multiply(int x, int y) { /// ``` void ignore() {} -/// you can ignore code sample by using `no-test` tag. +/// You can ignore code sample by using `dartdoc_test:ignore_error` tag. /// /// ```dart /// // dartdoc_test:ignore_error @@ -60,54 +72,3 @@ void ignore() {} /// tagIgnore() // it is not reported. /// ``` void tagIgnore() {} - -/// Should return: Expected to find ';'. -/// ```dart -/// final fact = factorial(5) -/// print(fact); // 120 -/// ``` -int factorial(int n) { - if (n < 0) throw ArgumentError('Negative numbers are not allowed.'); - return n == 0 ? 1 : n * factorial(n - 1); -} - -/// Checks if a string is a palindrome. -/// -/// This method ignores case and non-alphanumeric characters. -/// -/// Example: -/// ```dart -/// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); -/// print(isPalindrome); // true -/// ``` -bool isPalindrome(String s) { - var sanitized = s.replaceAll(RegExp(r'[^A-Za-z0-9]'), '').toLowerCase(); - return sanitized == sanitized.split('').reversed.join(''); -} - -/// Should return: Local variable 'gcd' can't be referenced before it is declared. -/// ```dart -/// final gcd = gcd(48, 18); -/// print(gcd); // 6 -/// ``` -int gcd(int a, int b) { - while (b != 0) { - var t = b; - b = a % b; - a = t; - } - return a; -} - -/// Convert a string to a list of lines. -/// -/// This method splits a string into lines using the newline character. -/// -/// Example: -/// ```dart -/// final lines = splitLines('Hello\nWorld'); -/// print(lines); // ['Hello', 'World'] -/// ``` -List splitLines(String s) { - return LineSplitter.split(s).toList(); -} diff --git a/dartdoc_test/example/lib/main.dart b/dartdoc_test/example/lib/main.dart deleted file mode 100644 index 9398c533..00000000 --- a/dartdoc_test/example/lib/main.dart +++ /dev/null @@ -1,33 +0,0 @@ -// Copyright 2023 Google LLC -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// https://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. - -/// Simple function that prints `"Hello world!"`. -/// -/// **Example** -/// ```dart -/// sayHello(); // prints: Hello world! -/// ``` -void sayHello() { - // My comment - print('Hello world!'); -} - -/// **Example** -/// ```dart -/// foo(); // prints: foo! -/// ``` -void foo() { - // My comment - print('foo!'); -} diff --git a/dartdoc_test/example/test/dartdoc_test.dart b/dartdoc_test/example/test/dartdoc_test.dart index cefeef4a..95482e99 100644 --- a/dartdoc_test/example/test/dartdoc_test.dart +++ b/dartdoc_test/example/test/dartdoc_test.dart @@ -19,6 +19,5 @@ import 'package:dartdoc_test/dartdoc_test.dart'; /// 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 [include] and [exclude] -/// options. +/// If you want to test only specific files, you can use [exclude] option. void main() => runDartdocTest(); diff --git a/dartdoc_test/lib/dartdoc_test.dart b/dartdoc_test/lib/dartdoc_test.dart index e4c0f803..8b98e1b1 100644 --- a/dartdoc_test/lib/dartdoc_test.dart +++ b/dartdoc_test/lib/dartdoc_test.dart @@ -26,7 +26,7 @@ import 'src/reporter.dart'; /// command `dart run dartdoc_test add`. /// /// In default, this function will test all code samples in your project. if you -/// want to test only specific files, you can use [include] and [exclude] options. +/// want to test only specific files, you can use [exclude] option. /// and if you need more logs, you can set [verbose] to true. void runDartdocTest({ List exclude = const [], diff --git a/dartdoc_test/lib/src/command/add.dart b/dartdoc_test/lib/src/command/add.dart index c2bfa9be..9931946d 100644 --- a/dartdoc_test/lib/src/command/add.dart +++ b/dartdoc_test/lib/src/command/add.dart @@ -56,8 +56,7 @@ import 'package:dartdoc_test/dartdoc_test.dart'; /// 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 [include] and [exclude] -/// options. +/// If you want to test only specific files, you can use [exclude] option. void main() => runDartdocTest(); '''; diff --git a/dartdoc_test/lib/src/logger.dart b/dartdoc_test/lib/src/logger.dart index 492ba1b7..fd0f5c0a 100644 --- a/dartdoc_test/lib/src/logger.dart +++ b/dartdoc_test/lib/src/logger.dart @@ -62,7 +62,7 @@ class Summary { factory Summary.from(List results) { final isFailed = results.indexWhere((r) => r.errors.isNotEmpty) != -1; final errors = - results.expand((r) => r.errors).where((e) => e.generatedSpan != null); + results.expand((r) => r.errors).where((e) => e.commentSpan != null); final samples = results.map((r) => r.file); final files = samples.map((s) => s.sample.comment.span.sourceUrl?.path).toSet(); diff --git a/dartdoc_test/lib/src/reporter.dart b/dartdoc_test/lib/src/reporter.dart index 9d3b95b5..dc0de5a7 100644 --- a/dartdoc_test/lib/src/reporter.dart +++ b/dartdoc_test/lib/src/reporter.dart @@ -133,15 +133,16 @@ final class _RepoterForTest extends Reporter } void _reportIssue(Issue issue) { - test( - 'test for ${issue.commentSpan?.text}', - () { - if (issue.commentSpan != null) { - fail(issue.commentSpan!.info(issue.message)); - } - }, - // skip: !_verbose && issue.generatedSpan == null, - ); + if (issue.commentSpan != null || _verbose) { + test( + 'test for ${issue.commentSpan?.text}', + () { + if (issue.commentSpan != null) { + fail(issue.commentSpan!.info(issue.message)); + } + }, + ); + } } } diff --git a/dartdoc_test/test/dartdoc_test.dart b/dartdoc_test/test/dartdoc_test.dart index e2eb3934..f5196794 100644 --- a/dartdoc_test/test/dartdoc_test.dart +++ b/dartdoc_test/test/dartdoc_test.dart @@ -1,11 +1,10 @@ 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 +/// +/// 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 [include] and [exclude] -/// options. +/// +/// If you want to test only specific files, you can use [exclude] option. void main() => runDartdocTest(); diff --git a/dartdoc_test/test/testdata/codeSample/error_example_0.dart b/dartdoc_test/test/testdata/codeSample/error_example_0.dart new file mode 100644 index 00000000..65dc0e90 --- /dev/null +++ b/dartdoc_test/test/testdata/codeSample/error_example_0.dart @@ -0,0 +1,7 @@ + +import '../../../example/lib/error_example.dart'; + +void main() { + final fact = factorial(5) + print(fact); // 120 +} diff --git a/dartdoc_test/test/testdata/codeSample/example_5.dart b/dartdoc_test/test/testdata/codeSample/error_example_1.dart similarity index 63% rename from dartdoc_test/test/testdata/codeSample/example_5.dart rename to dartdoc_test/test/testdata/codeSample/error_example_1.dart index 587c5499..70691161 100644 --- a/dartdoc_test/test/testdata/codeSample/example_5.dart +++ b/dartdoc_test/test/testdata/codeSample/error_example_1.dart @@ -1,5 +1,5 @@ -import 'dart:convert'; -import '../../../example/lib/example.dart'; + +import '../../../example/lib/error_example.dart'; void main() { final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); diff --git a/dartdoc_test/test/testdata/codeSample/error_example_2.dart b/dartdoc_test/test/testdata/codeSample/error_example_2.dart new file mode 100644 index 00000000..9f98bf5d --- /dev/null +++ b/dartdoc_test/test/testdata/codeSample/error_example_2.dart @@ -0,0 +1,7 @@ + +import '../../../example/lib/error_example.dart'; + +void main() { + final gcd = gcd(48, 18); + print(gcd); // 6 +} diff --git a/dartdoc_test/test/testdata/codeSample/error_example_3.dart b/dartdoc_test/test/testdata/codeSample/error_example_3.dart new file mode 100644 index 00000000..2f1a97cb --- /dev/null +++ b/dartdoc_test/test/testdata/codeSample/error_example_3.dart @@ -0,0 +1,7 @@ + +import '../../../example/lib/error_example.dart'; + +void main() { + final length = 5.length; + print(length); // 1 +} diff --git a/dartdoc_test/test/testdata/codeSample/example_1.dart b/dartdoc_test/test/testdata/codeSample/example_1.dart index c1c70d4d..1352371c 100644 --- a/dartdoc_test/test/testdata/codeSample/example_1.dart +++ b/dartdoc_test/test/testdata/codeSample/example_1.dart @@ -2,6 +2,6 @@ import 'dart:convert'; import '../../../example/lib/example.dart'; void main() { - final result = multiply(4, 5); - print(result); // 20 + final result = subtract(5, 3); + print(result); // 2 } diff --git a/dartdoc_test/test/testdata/codeSample/example_2.dart b/dartdoc_test/test/testdata/codeSample/example_2.dart index 519fe1ea..c1c70d4d 100644 --- a/dartdoc_test/test/testdata/codeSample/example_2.dart +++ b/dartdoc_test/test/testdata/codeSample/example_2.dart @@ -2,6 +2,6 @@ import 'dart:convert'; import '../../../example/lib/example.dart'; void main() { - final result = multiply(6, 7); - print(result); // 42 + final result = multiply(4, 5); + print(result); // 20 } diff --git a/dartdoc_test/test/testdata/codeSample/example_4.dart b/dartdoc_test/test/testdata/codeSample/example_3.dart similarity index 60% rename from dartdoc_test/test/testdata/codeSample/example_4.dart rename to dartdoc_test/test/testdata/codeSample/example_3.dart index 0c23ca45..519fe1ea 100644 --- a/dartdoc_test/test/testdata/codeSample/example_4.dart +++ b/dartdoc_test/test/testdata/codeSample/example_3.dart @@ -2,6 +2,6 @@ import 'dart:convert'; import '../../../example/lib/example.dart'; void main() { - final fact = factorial(5) - print(fact); // 120 + final result = multiply(6, 7); + print(result); // 42 } diff --git a/dartdoc_test/test/testdata/codeSample/example_6.dart b/dartdoc_test/test/testdata/codeSample/example_6.dart deleted file mode 100644 index d562f5d7..00000000 --- a/dartdoc_test/test/testdata/codeSample/example_6.dart +++ /dev/null @@ -1,7 +0,0 @@ -import 'dart:convert'; -import '../../../example/lib/example.dart'; - -void main() { - final gcd = gcd(48, 18); - print(gcd); // 6 -} diff --git a/dartdoc_test/test/testdata/codeSample/example_7.dart b/dartdoc_test/test/testdata/codeSample/example_7.dart deleted file mode 100644 index 67a4e066..00000000 --- a/dartdoc_test/test/testdata/codeSample/example_7.dart +++ /dev/null @@ -1,7 +0,0 @@ -import 'dart:convert'; -import '../../../example/lib/example.dart'; - -void main() { - final lines = splitLines('Hello\nWorld'); - print(lines); // ['Hello', 'World'] -} diff --git a/dartdoc_test/test/testdata/codeSample/main_0.dart b/dartdoc_test/test/testdata/codeSample/main_0.dart deleted file mode 100644 index f56779a5..00000000 --- a/dartdoc_test/test/testdata/codeSample/main_0.dart +++ /dev/null @@ -1,6 +0,0 @@ - -import '../../../example/lib/main.dart'; - -void main() { - sayHello(); // prints: Hello world! -} diff --git a/dartdoc_test/test/testdata/codeSample/main_1.dart b/dartdoc_test/test/testdata/codeSample/main_1.dart deleted file mode 100644 index 7260e4f9..00000000 --- a/dartdoc_test/test/testdata/codeSample/main_1.dart +++ /dev/null @@ -1,6 +0,0 @@ - -import '../../../example/lib/main.dart'; - -void main() { - foo(); // prints: foo! -} diff --git a/dartdoc_test/test/testdata/dartdoc_test.txt b/dartdoc_test/test/testdata/dartdoc_test.txt index d85b4846..85b64012 100644 --- a/dartdoc_test/test/testdata/dartdoc_test.txt +++ b/dartdoc_test/test/testdata/dartdoc_test.txt @@ -1,70 +1,47 @@ 00:00 +0: loading example/test/dartdoc_test.dart Extracting code samples ... Analyzing code samples ... -00:00 +0: [dartdoc_test] example/lib/example.dart test for null -00:00 +1: [dartdoc_test] example/lib/example.dart test for null -00:00 +2: [dartdoc_test] example/lib/example.dart test for null -00:00 +3: [dartdoc_test] example/lib/example.dart test for ) -00:00 +3 -1: [dartdoc_test] example/lib/example.dart test for ) [E] - example/lib/example.dart:66:29: : Expected to find ';'. +00:00 +0: [dartdoc_test] example/lib/error_example.dart test for ) +00:00 +0 -1: [dartdoc_test] example/lib/error_example.dart test for ) [E] + example/lib/error_example.dart:17:29: : Expected to find ';'. ╷ - 66 │ /// final fact = factorial(5) + 17 │ /// final fact = factorial(5) │ ^ ╵ package:matcher fail - package:dartdoc_test/src/reporter.dart 140:11 _RepoterForTest._reportIssue. + package:dartdoc_test/src/reporter.dart 141:13 _RepoterForTest._reportIssue. -00:00 +3 -1: [dartdoc_test] example/lib/example.dart test for null -00:00 +4 -1: [dartdoc_test] example/lib/example.dart test for isPalindrome -00:00 +4 -2: [dartdoc_test] example/lib/example.dart test for isPalindrome [E] - example/lib/example.dart:80:11: : Local variable 'isPalindrome' can't be referenced before it is declared. +00:00 +0 -1: [dartdoc_test] example/lib/error_example.dart test for isPalindrome +00:00 +0 -2: [dartdoc_test] example/lib/error_example.dart test for isPalindrome [E] + example/lib/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. ╷ - 80 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); + 31 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); │ ^^^^^^^^^^^^ ╵ package:matcher fail - package:dartdoc_test/src/reporter.dart 140:11 _RepoterForTest._reportIssue. + package:dartdoc_test/src/reporter.dart 141:13 _RepoterForTest._reportIssue. -00:00 +4 -2: [dartdoc_test] example/lib/example.dart test for null -00:00 +5 -2: [dartdoc_test] example/lib/example.dart test for null -00:00 +6 -2: [dartdoc_test] example/lib/example.dart test for gcd -00:00 +6 -3: [dartdoc_test] example/lib/example.dart test for gcd [E] - example/lib/example.dart:88:36: : Local variable 'gcd' can't be referenced before it is declared. +00:00 +0 -2: [dartdoc_test] example/lib/error_example.dart test for gcd +00:00 +0 -3: [dartdoc_test] example/lib/error_example.dart test for gcd [E] + example/lib/error_example.dart:39:36: : Local variable 'gcd' can't be referenced before it is declared. ╷ - 88 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. + 39 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. │ ^^^ ╵ package:matcher fail - package:dartdoc_test/src/reporter.dart 140:11 _RepoterForTest._reportIssue. + package:dartdoc_test/src/reporter.dart 141:13 _RepoterForTest._reportIssue. -00:00 +6 -3: [dartdoc_test] example/lib/example.dart test for null -00:00 +7 -3: [dartdoc_test] example/lib/example.dart test for null -00:00 +8 -3: [dartdoc_test] example/lib/example.dart test for null -00:00 +9 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +10 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +11 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +12 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +13 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +14 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +15 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +16 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +17 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +18 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +19 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +20 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +21 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +22 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +23 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +24 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +25 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +26 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +27 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +28 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +29 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +30 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +31 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +32 -3: [dartdoc_test] lib/src/extractor.dart test for null -00:00 +33 -3: Some tests failed. +00:00 +0 -3: [dartdoc_test] example/lib/error_example.dart test for length +00:00 +0 -4: [dartdoc_test] example/lib/error_example.dart test for length [E] + example/lib/error_example.dart:53:32: : The getter 'length' isn't defined for the type 'int'. + ╷ + 53 │ /// Should return: The getter 'length' isn't defined for the class 'int'. + │ ^^^^^^ + ╵ + package:matcher fail + package:dartdoc_test/src/reporter.dart 141:13 _RepoterForTest._reportIssue. + +00:00 +0 -4: Some tests failed. Consider enabling the flag chain-stack-traces to receive more detailed exceptions. For example, 'dart test --chain-stack-traces'. diff --git a/dartdoc_test/test/testdata/dartdoc_test_example.txt b/dartdoc_test/test/testdata/dartdoc_test_example.txt index 52a18b03..fe4dce31 100644 --- a/dartdoc_test/test/testdata/dartdoc_test_example.txt +++ b/dartdoc_test/test/testdata/dartdoc_test_example.txt @@ -1,46 +1,47 @@ 00:00 +0: loading test/dartdoc_test.dart Extracting code samples ... Analyzing code samples ... -00:00 +0: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null -00:00 +1: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null -00:00 +2: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null -00:00 +3: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for ) -00:00 +3 -1: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for ) [E] - package:example/example.dart:66:29: : Expected to find ';'. +00:00 +0: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for ) +00:00 +0 -1: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for ) [E] + package:example/error_example.dart:17:29: : Expected to find ';'. ╷ - 66 │ /// final fact = factorial(5) + 17 │ /// final fact = factorial(5) │ ^ ╵ package:matcher fail - package:dartdoc_test/src/reporter.dart 140:11 _RepoterForTest._reportIssue. + package:dartdoc_test/src/reporter.dart 141:13 _RepoterForTest._reportIssue. -00:00 +3 -1: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null -00:00 +4 -1: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for isPalindrome -00:00 +4 -2: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for isPalindrome [E] - package:example/example.dart:80:11: : Local variable 'isPalindrome' can't be referenced before it is declared. +00:00 +0 -1: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for isPalindrome +00:00 +0 -2: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for isPalindrome [E] + package:example/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. ╷ - 80 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); + 31 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); │ ^^^^^^^^^^^^ ╵ package:matcher fail - package:dartdoc_test/src/reporter.dart 140:11 _RepoterForTest._reportIssue. + package:dartdoc_test/src/reporter.dart 141:13 _RepoterForTest._reportIssue. -00:00 +4 -2: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null -00:00 +5 -2: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null -00:00 +6 -2: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for gcd -00:00 +6 -3: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for gcd [E] - package:example/example.dart:88:36: : Local variable 'gcd' can't be referenced before it is declared. +00:00 +0 -2: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for gcd +00:00 +0 -3: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for gcd [E] + package:example/error_example.dart:39:36: : Local variable 'gcd' can't be referenced before it is declared. ╷ - 88 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. + 39 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. │ ^^^ ╵ package:matcher fail - package:dartdoc_test/src/reporter.dart 140:11 _RepoterForTest._reportIssue. + package:dartdoc_test/src/reporter.dart 141:13 _RepoterForTest._reportIssue. -00:00 +6 -3: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null -00:00 +7 -3: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null -00:00 +8 -3: test/dartdoc_test.dart: [dartdoc_test] lib/example.dart test for null -00:00 +9 -3: Some tests failed. +00:00 +0 -3: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for length +00:00 +0 -4: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for length [E] + package:example/error_example.dart:53:32: : The getter 'length' isn't defined for the type 'int'. + ╷ + 53 │ /// Should return: The getter 'length' isn't defined for the class 'int'. + │ ^^^^^^ + ╵ + package:matcher fail + package:dartdoc_test/src/reporter.dart 141:13 _RepoterForTest._reportIssue. + +00:00 +0 -4: Some tests failed. Consider enabling the flag chain-stack-traces to receive more detailed exceptions. For example, 'dart test --chain-stack-traces'. diff --git a/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt b/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt index d5aed189..1b0844a2 100644 --- a/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt +++ b/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt @@ -1,36 +1,41 @@ $ dart run bin/dartdoc_test.dart -v Extracting code samples ... Analyzing code samples ... -.dartdoc_test/example_0.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_1.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_2.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -original error: .dartdoc_test/example_4.dart:5:27: Expected to find ';'. -example/lib/example.dart:66:29: : Expected to find ';'. +original error: .dartdoc_test/error_example_0.dart:5:27: Expected to find ';'. +example/lib/error_example.dart:17:29: : Expected to find ';'. ╷ -66 │ /// final fact = factorial(5) +17 │ /// final fact = factorial(5) │ ^ ╵ -.dartdoc_test/example_4.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -original error: .dartdoc_test/example_5.dart:5:24: Local variable 'isPalindrome' can't be referenced before it is declared. -example/lib/example.dart:80:11: : Local variable 'isPalindrome' can't be referenced before it is declared. +original error: .dartdoc_test/error_example_1.dart:5:24: Local variable 'isPalindrome' can't be referenced before it is declared. +example/lib/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. ╷ -80 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); +31 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); │ ^^^^^^^^^^^^ ╵ -.dartdoc_test/example_5.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_5.dart:2:8: Unused import: '../example/lib/example.dart'. (ignored because issue occurs in the generated code) -original error: .dartdoc_test/example_6.dart:5:15: Local variable 'gcd' can't be referenced before it is declared. -example/lib/example.dart:88:36: : Local variable 'gcd' can't be referenced before it is declared. +.dartdoc_test/error_example_1.dart:2:8: Unused import: '../example/lib/error_example.dart'. (ignored because issue occurs in the generated code) +original error: .dartdoc_test/error_example_2.dart:5:15: Local variable 'gcd' can't be referenced before it is declared. +example/lib/error_example.dart:39:36: : Local variable 'gcd' can't be referenced before it is declared. ╷ -88 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. +39 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. │ ^^^ ╵ -.dartdoc_test/example_6.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_6.dart:2:8: Unused import: '../example/lib/example.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_7.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/error_example_2.dart:2:8: Unused import: '../example/lib/error_example.dart'. (ignored because issue occurs in the generated code) +original error: .dartdoc_test/error_example_3.dart:5:20: The getter 'length' isn't defined for the type 'int'. +example/lib/error_example.dart:53:32: : The getter 'length' isn't defined for the type 'int'. + ╷ +53 │ /// Should return: The getter 'length' isn't defined for the class 'int'. + │ ^^^^^^ + ╵ + +.dartdoc_test/error_example_3.dart:2:8: Unused import: '../example/lib/error_example.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/example_0.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/example_1.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/example_2.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/example_3.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) .dartdoc_test/extractor_0.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) .dartdoc_test/extractor_0.dart:2:8: Unused import: 'dart:io'. (ignored because issue occurs in the generated code) .dartdoc_test/extractor_0.dart:3:8: Unused import: 'package:path/path.dart'. (ignored because issue occurs in the generated code) @@ -55,4 +60,4 @@ example/lib/example.dart:88:36: : Local variable 'gcd' can't be referenced befor .dartdoc_test/extractor_2.dart:6:8: Unused import: 'package:analyzer/dart/ast/visitor.dart'. (ignored because issue occurs in the generated code) .dartdoc_test/extractor_2.dart:7:8: Unused import: 'package:markdown/markdown.dart'. (ignored because issue occurs in the generated code) .dartdoc_test/extractor_2.dart:8:8: Unused import: 'package:source_span/source_span.dart'. (ignored because issue occurs in the generated code) -FAILED: 36 issues found (Found 12 code samples in 3 files) \ No newline at end of file +FAILED: 4 issues found (Found 11 code samples in 3 files) \ No newline at end of file diff --git a/dartdoc_test/test/testdata/run analyze command by default.txt b/dartdoc_test/test/testdata/run analyze command by default.txt index d24a1556..98ba2845 100644 --- a/dartdoc_test/test/testdata/run analyze command by default.txt +++ b/dartdoc_test/test/testdata/run analyze command by default.txt @@ -1,22 +1,28 @@ $ dart run bin/dartdoc_test.dart Extracting code samples ... Analyzing code samples ... -example/lib/example.dart:66:29: : Expected to find ';'. +example/lib/error_example.dart:17:29: : Expected to find ';'. ╷ -66 │ /// final fact = factorial(5) +17 │ /// final fact = factorial(5) │ ^ ╵ -example/lib/example.dart:80:11: : Local variable 'isPalindrome' can't be referenced before it is declared. +example/lib/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. ╷ -80 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); +31 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); │ ^^^^^^^^^^^^ ╵ -example/lib/example.dart:88:36: : Local variable 'gcd' can't be referenced before it is declared. +example/lib/error_example.dart:39:36: : Local variable 'gcd' can't be referenced before it is declared. ╷ -88 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. +39 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. │ ^^^ ╵ -FAILED: 36 issues found (Found 12 code samples in 3 files) \ No newline at end of file +example/lib/error_example.dart:53:32: : The getter 'length' isn't defined for the type 'int'. + ╷ +53 │ /// Should return: The getter 'length' isn't defined for the class 'int'. + │ ^^^^^^ + ╵ + +FAILED: 4 issues found (Found 11 code samples in 3 files) \ No newline at end of file diff --git a/dartdoc_test/test/testdata/run analyze command with exclude option.txt b/dartdoc_test/test/testdata/run analyze command with exclude option.txt index bf6627e3..dab5d5d0 100644 --- a/dartdoc_test/test/testdata/run analyze command with exclude option.txt +++ b/dartdoc_test/test/testdata/run analyze command with exclude option.txt @@ -1,22 +1,28 @@ $ dart run bin/dartdoc_test.dart analyze -x lib/** Extracting code samples ... Analyzing code samples ... -example/lib/example.dart:66:29: : Expected to find ';'. +example/lib/error_example.dart:17:29: : Expected to find ';'. ╷ -66 │ /// final fact = factorial(5) +17 │ /// final fact = factorial(5) │ ^ ╵ -example/lib/example.dart:80:11: : Local variable 'isPalindrome' can't be referenced before it is declared. +example/lib/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. ╷ -80 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); +31 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); │ ^^^^^^^^^^^^ ╵ -example/lib/example.dart:88:36: : Local variable 'gcd' can't be referenced before it is declared. +example/lib/error_example.dart:39:36: : Local variable 'gcd' can't be referenced before it is declared. ╷ -88 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. +39 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. │ ^^^ ╵ -FAILED: 12 issues found (Found 9 code samples in 2 files) \ No newline at end of file +example/lib/error_example.dart:53:32: : The getter 'length' isn't defined for the type 'int'. + ╷ +53 │ /// Should return: The getter 'length' isn't defined for the class 'int'. + │ ^^^^^^ + ╵ + +FAILED: 4 issues found (Found 8 code samples in 2 files) \ No newline at end of file diff --git a/dartdoc_test/test/testdata/run analyze command with verbose flag.txt b/dartdoc_test/test/testdata/run analyze command with verbose flag.txt index 3bc610e8..a90b2199 100644 --- a/dartdoc_test/test/testdata/run analyze command with verbose flag.txt +++ b/dartdoc_test/test/testdata/run analyze command with verbose flag.txt @@ -1,36 +1,41 @@ $ dart run bin/dartdoc_test.dart analyze -v Extracting code samples ... Analyzing code samples ... -.dartdoc_test/example_0.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_1.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_2.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -original error: .dartdoc_test/example_4.dart:5:27: Expected to find ';'. -example/lib/example.dart:66:29: : Expected to find ';'. +original error: .dartdoc_test/error_example_0.dart:5:27: Expected to find ';'. +example/lib/error_example.dart:17:29: : Expected to find ';'. ╷ -66 │ /// final fact = factorial(5) +17 │ /// final fact = factorial(5) │ ^ ╵ -.dartdoc_test/example_4.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -original error: .dartdoc_test/example_5.dart:5:24: Local variable 'isPalindrome' can't be referenced before it is declared. -example/lib/example.dart:80:11: : Local variable 'isPalindrome' can't be referenced before it is declared. +original error: .dartdoc_test/error_example_1.dart:5:24: Local variable 'isPalindrome' can't be referenced before it is declared. +example/lib/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. ╷ -80 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); +31 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); │ ^^^^^^^^^^^^ ╵ -.dartdoc_test/example_5.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_5.dart:2:8: Unused import: '../example/lib/example.dart'. (ignored because issue occurs in the generated code) -original error: .dartdoc_test/example_6.dart:5:15: Local variable 'gcd' can't be referenced before it is declared. -example/lib/example.dart:88:36: : Local variable 'gcd' can't be referenced before it is declared. +.dartdoc_test/error_example_1.dart:2:8: Unused import: '../example/lib/error_example.dart'. (ignored because issue occurs in the generated code) +original error: .dartdoc_test/error_example_2.dart:5:15: Local variable 'gcd' can't be referenced before it is declared. +example/lib/error_example.dart:39:36: : Local variable 'gcd' can't be referenced before it is declared. ╷ -88 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. +39 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. │ ^^^ ╵ -.dartdoc_test/example_6.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_6.dart:2:8: Unused import: '../example/lib/example.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_7.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/error_example_2.dart:2:8: Unused import: '../example/lib/error_example.dart'. (ignored because issue occurs in the generated code) +original error: .dartdoc_test/error_example_3.dart:5:20: The getter 'length' isn't defined for the type 'int'. +example/lib/error_example.dart:53:32: : The getter 'length' isn't defined for the type 'int'. + ╷ +53 │ /// Should return: The getter 'length' isn't defined for the class 'int'. + │ ^^^^^^ + ╵ + +.dartdoc_test/error_example_3.dart:2:8: Unused import: '../example/lib/error_example.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/example_0.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/example_1.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/example_2.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/example_3.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) .dartdoc_test/extractor_0.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) .dartdoc_test/extractor_0.dart:2:8: Unused import: 'dart:io'. (ignored because issue occurs in the generated code) .dartdoc_test/extractor_0.dart:3:8: Unused import: 'package:path/path.dart'. (ignored because issue occurs in the generated code) @@ -55,4 +60,4 @@ example/lib/example.dart:88:36: : Local variable 'gcd' can't be referenced befor .dartdoc_test/extractor_2.dart:6:8: Unused import: 'package:analyzer/dart/ast/visitor.dart'. (ignored because issue occurs in the generated code) .dartdoc_test/extractor_2.dart:7:8: Unused import: 'package:markdown/markdown.dart'. (ignored because issue occurs in the generated code) .dartdoc_test/extractor_2.dart:8:8: Unused import: 'package:source_span/source_span.dart'. (ignored because issue occurs in the generated code) -FAILED: 36 issues found (Found 12 code samples in 3 files) \ No newline at end of file +FAILED: 4 issues found (Found 11 code samples in 3 files) \ No newline at end of file diff --git a/dartdoc_test/test/testdata/run analyze command.txt b/dartdoc_test/test/testdata/run analyze command.txt index 20733a3d..8ccf3476 100644 --- a/dartdoc_test/test/testdata/run analyze command.txt +++ b/dartdoc_test/test/testdata/run analyze command.txt @@ -1,22 +1,28 @@ $ dart run bin/dartdoc_test.dart analyze Extracting code samples ... Analyzing code samples ... -example/lib/example.dart:66:29: : Expected to find ';'. +example/lib/error_example.dart:17:29: : Expected to find ';'. ╷ -66 │ /// final fact = factorial(5) +17 │ /// final fact = factorial(5) │ ^ ╵ -example/lib/example.dart:80:11: : Local variable 'isPalindrome' can't be referenced before it is declared. +example/lib/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. ╷ -80 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); +31 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); │ ^^^^^^^^^^^^ ╵ -example/lib/example.dart:88:36: : Local variable 'gcd' can't be referenced before it is declared. +example/lib/error_example.dart:39:36: : Local variable 'gcd' can't be referenced before it is declared. ╷ -88 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. +39 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. │ ^^^ ╵ -FAILED: 36 issues found (Found 12 code samples in 3 files) \ No newline at end of file +example/lib/error_example.dart:53:32: : The getter 'length' isn't defined for the type 'int'. + ╷ +53 │ /// Should return: The getter 'length' isn't defined for the class 'int'. + │ ^^^^^^ + ╵ + +FAILED: 4 issues found (Found 11 code samples in 3 files) \ No newline at end of file From 1467c6b86c444ca9d4584586fcf9dad9aaf1f022 Mon Sep 17 00:00:00 2001 From: takumma Date: Sun, 11 Aug 2024 10:53:25 +0900 Subject: [PATCH 07/23] move models to model.dart --- dartdoc_test/lib/src/analyzer.dart | 3 +- dartdoc_test/lib/src/dartdoc_test.dart | 1 + dartdoc_test/lib/src/extractor.dart | 67 +--------------- dartdoc_test/lib/src/model.dart | 104 +++++++++++++++++++++++++ dartdoc_test/lib/src/resource.dart | 17 +--- 5 files changed, 111 insertions(+), 81 deletions(-) create mode 100644 dartdoc_test/lib/src/model.dart diff --git a/dartdoc_test/lib/src/analyzer.dart b/dartdoc_test/lib/src/analyzer.dart index 37768aa3..651ef634 100644 --- a/dartdoc_test/lib/src/analyzer.dart +++ b/dartdoc_test/lib/src/analyzer.dart @@ -15,9 +15,10 @@ import 'package:analyzer/dart/analysis/analysis_context.dart'; import 'package:analyzer/dart/analysis/results.dart'; import 'package:analyzer/error/error.dart'; -import 'package:dartdoc_test/src/resource.dart'; import 'package:source_span/source_span.dart'; +import 'model.dart'; + Future getAnalysisResult( AnalysisContext context, CodeSampleFile file, diff --git a/dartdoc_test/lib/src/dartdoc_test.dart b/dartdoc_test/lib/src/dartdoc_test.dart index 3dbb7729..e2b062d0 100644 --- a/dartdoc_test/lib/src/dartdoc_test.dart +++ b/dartdoc_test/lib/src/dartdoc_test.dart @@ -79,6 +79,7 @@ class DartdocTestOptions { write: args.flag('write'), verbose: args.flag('verbose'), out: args.option('output'), + exclude: args.multiOption('exclude'), ); } } diff --git a/dartdoc_test/lib/src/extractor.dart b/dartdoc_test/lib/src/extractor.dart index f9bdc725..5e2153a3 100644 --- a/dartdoc_test/lib/src/extractor.dart +++ b/dartdoc_test/lib/src/extractor.dart @@ -13,8 +13,6 @@ // limitations under the License. import 'dart:convert'; -import 'dart:io'; -import 'package:path/path.dart' as p; import 'package:analyzer/dart/analysis/results.dart'; import 'package:analyzer/dart/ast/ast.dart'; @@ -22,70 +20,9 @@ import 'package:analyzer/dart/ast/visitor.dart'; import 'package:markdown/markdown.dart'; import 'package:source_span/source_span.dart'; -final _md = Document(extensionSet: ExtensionSet.gitHubWeb); - -/// A documentation comment extracted from a source file. -class DocumentationComment { - /// The path of the original file - final String path; - - /// The span of the comment in the source file. - final FileSpan span; - - /// The contents of the comment. (includes code blocks and text) - final String contents; - - /// The imports used in the source file. - final List imports; - - DocumentationComment({ - required this.path, - required this.contents, - required this.span, - required this.imports, - }); -} +import 'model.dart'; -/// A code sample extracted from a documentation comment. -class DocumentationCodeSample { - /// The documentation comment that contains the code sample. - final DocumentationComment comment; - - /// content of the code sample. - final String code; - - DocumentationCodeSample({ - required this.comment, - required this.code, - }); - - bool get ignore => code.contains('// dartdoc_test:ignore_error'); - bool get hasMain => code.contains('void main()'); - bool get hasImport => code.contains('import '); - - /// Create a sample by wrapping the code with a main function and imports. - String wrappedCode(Directory testDir) { - final fileName = comment.span.sourceUrl; - - final buf = StringBuffer(); - buf.writeAll(comment.imports, '\n'); - buf.writeln(); - if (fileName != null) { - if (fileName.hasAbsolutePath) { - final path = p.relative(fileName.path, from: testDir.absolute.path); - buf.writeln('import \'$path\';'); - } else { - buf.writeln('import \'$fileName\';'); - } - } - buf.writeln(); - buf.writeln('void main() {'); - buf.writeAll(LineSplitter.split(code).map((l) => ' $l'), '\n'); - buf.writeln(); - buf.writeln('}'); - return buf.toString(); - } -} +final _md = Document(extensionSet: ExtensionSet.gitHubWeb); List extractFile( ParsedUnitResult result, diff --git a/dartdoc_test/lib/src/model.dart b/dartdoc_test/lib/src/model.dart new file mode 100644 index 00000000..79d14030 --- /dev/null +++ b/dartdoc_test/lib/src/model.dart @@ -0,0 +1,104 @@ +// Copyright 2023 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// https://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +import 'dart:convert'; +import 'dart:io'; + +import 'package:path/path.dart' as p; +import 'package:source_span/source_span.dart'; + +class DartdocTestFile { + const DartdocTestFile(this._comments, this._sourceFile); + + final List _comments; + final FileSpan _sourceFile; + + List get comments => _comments; + FileSpan get sourceFile => _sourceFile; +} + +/// A documentation comment extracted from a source file. +class DocumentationComment { + /// The path of the original file + final String path; + + /// The span of the comment in the source file. + final FileSpan span; + + /// The contents of the comment. (includes code blocks and text) + final String contents; + + /// The imports used in the source file. + final List imports; + + DocumentationComment({ + required this.path, + required this.contents, + required this.span, + required this.imports, + }); +} + +/// A code sample extracted from a documentation comment. +class DocumentationCodeSample { + /// The documentation comment that contains the code sample. + final DocumentationComment comment; + + /// content of the code sample. + final String code; + + DocumentationCodeSample({ + required this.comment, + required this.code, + }); + + bool get ignore => code.contains('// dartdoc_test:ignore_error'); + bool get hasMain => code.contains('void main()'); + bool get hasImport => code.contains('import '); + + /// Create a sample by wrapping the code with a main function and imports. + String wrappedCode(Directory testDir) { + final fileName = comment.span.sourceUrl; + + final buf = StringBuffer(); + buf.writeAll(comment.imports, '\n'); + buf.writeln(); + if (fileName != null) { + if (fileName.hasAbsolutePath) { + final path = p.relative(fileName.path, from: testDir.absolute.path); + buf.writeln('import \'$path\';'); + } else { + buf.writeln('import \'$fileName\';'); + } + } + buf.writeln(); + buf.writeln('void main() {'); + buf.writeAll(LineSplitter.split(code).map((l) => ' $l'), '\n'); + buf.writeln(); + buf.writeln('}'); + return buf.toString(); + } +} + +class CodeSampleFile { + final String path; + final SourceFile sourceFile; + final DocumentationCodeSample sample; + + CodeSampleFile({ + required this.path, + required this.sourceFile, + required this.sample, + }); +} diff --git a/dartdoc_test/lib/src/resource.dart b/dartdoc_test/lib/src/resource.dart index 65664d2e..eaf92933 100644 --- a/dartdoc_test/lib/src/resource.dart +++ b/dartdoc_test/lib/src/resource.dart @@ -22,14 +22,13 @@ import 'package:path/path.dart' as p; import 'package:source_span/source_span.dart'; import 'dartdoc_test.dart'; -import 'extractor.dart'; +import 'model.dart'; const _testPath = '.dartdoc_test'; final currentDir = Directory.current; -/// Context for running tests. -/// manage [resourceProvider]. +/// Context for running tests. manage [resourceProvider]. class DartdocTestContext { DartdocTestContext(this.options) { _resourceProvider = OverlayResourceProvider( @@ -118,15 +117,3 @@ class DartdocTestContext { return files; } } - -class CodeSampleFile { - final String path; - final SourceFile sourceFile; - final DocumentationCodeSample sample; - - CodeSampleFile({ - required this.path, - required this.sourceFile, - required this.sample, - }); -} From 7eaa0c179196477cae3df54eda9edccdf12f5ae2 Mon Sep 17 00:00:00 2001 From: takumma Date: Sun, 11 Aug 2024 14:08:26 +0900 Subject: [PATCH 08/23] only run integration test on ./example --- dartdoc_test/lib/src/extractor.dart | 9 ++++ dartdoc_test/lib/src/model.dart | 35 ++++++++++------ dartdoc_test/test/integration_test.dart | 29 +++---------- .../testdata/codeSample/error_example_0.dart | 2 +- .../testdata/codeSample/error_example_1.dart | 2 +- .../testdata/codeSample/error_example_2.dart | 2 +- .../testdata/codeSample/error_example_3.dart | 2 +- .../test/testdata/codeSample/example_0.dart | 2 +- .../test/testdata/codeSample/example_1.dart | 2 +- .../test/testdata/codeSample/example_2.dart | 2 +- .../test/testdata/codeSample/example_3.dart | 2 +- .../test/testdata/codeSample/extractor_0.dart | 14 ------- .../test/testdata/codeSample/extractor_1.dart | 14 ------- .../test/testdata/codeSample/extractor_2.dart | 17 -------- dartdoc_test/test/testdata/dartdoc_test.txt | 26 ++++++------ ...e command by default with verbose flag.txt | 42 ++++--------------- .../run analyze command by default.txt | 12 +++--- ...un analyze command with exclude option.txt | 29 ++----------- .../run analyze command with verbose flag.txt | 42 ++++--------------- .../test/testdata/run analyze command.txt | 12 +++--- dartdoc_test/test/testdata/show help.txt | 2 +- 21 files changed, 91 insertions(+), 208 deletions(-) delete mode 100644 dartdoc_test/test/testdata/codeSample/extractor_0.dart delete mode 100644 dartdoc_test/test/testdata/codeSample/extractor_1.dart delete mode 100644 dartdoc_test/test/testdata/codeSample/extractor_2.dart diff --git a/dartdoc_test/lib/src/extractor.dart b/dartdoc_test/lib/src/extractor.dart index 5e2153a3..03fc840a 100644 --- a/dartdoc_test/lib/src/extractor.dart +++ b/dartdoc_test/lib/src/extractor.dart @@ -224,3 +224,12 @@ class _ForEachText extends NodeVisitor { @override void visitText(Text text) => _forEach(text); } + +extension on DartdocTestFile { + static DartdocTestFile from(ParsedUnitResult result) { + final sourceFile = SourceFile.fromString(result.content, url: result.uri); + final comments = extractDocumentationComments(result); + final imports = getImports(sourceFile, result); + return DartdocTestFile(sourceFile, imports, comments); + } +} diff --git a/dartdoc_test/lib/src/model.dart b/dartdoc_test/lib/src/model.dart index 79d14030..490b70ee 100644 --- a/dartdoc_test/lib/src/model.dart +++ b/dartdoc_test/lib/src/model.dart @@ -19,35 +19,44 @@ import 'package:path/path.dart' as p; import 'package:source_span/source_span.dart'; class DartdocTestFile { - const DartdocTestFile(this._comments, this._sourceFile); + DartdocTestFile(this._sourceFile, this._imports, this._comments); + final SourceFile _sourceFile; + final List _imports; final List _comments; - final FileSpan _sourceFile; + SourceFile get sourceFile => _sourceFile; + List get imports => _imports; List get comments => _comments; - FileSpan get sourceFile => _sourceFile; } /// A documentation comment extracted from a source file. class DocumentationComment { - /// The path of the original file - final String path; + final String _path; /// The span of the comment in the source file. - final FileSpan span; + final FileSpan _span; /// The contents of the comment. (includes code blocks and text) - final String contents; + final String _contents; /// The imports used in the source file. - final List imports; + final List _imports; + + String get path => _path; + FileSpan get span => _span; + String get contents => _contents; + List get imports => _imports; DocumentationComment({ - required this.path, - required this.contents, - required this.span, - required this.imports, - }); + required String path, + required String contents, + required FileSpan span, + required List imports, + }) : _path = path, + _contents = contents, + _span = span, + _imports = imports; } /// A code sample extracted from a documentation comment. diff --git a/dartdoc_test/test/integration_test.dart b/dartdoc_test/test/integration_test.dart index 9e224ab7..17ca1eba 100644 --- a/dartdoc_test/test/integration_test.dart +++ b/dartdoc_test/test/integration_test.dart @@ -30,33 +30,13 @@ void main() { group('extractor', () { test('extract code samples in example directory', () async { final process = - await execute(['analyze', '-w', '-o', 'test/testdata/codeSample']); + await execute(['analyze', '-w', '-o', '../test/testdata/codeSample']); await process.shouldExit(0); }); }); group('dart test', () { test('run dartdoc_test', () async { - final args = [ - 'test', - '--no-color', - '-r', - 'expanded', - 'example/test/dartdoc_test.dart' - ]; - final process = await Process.run( - 'dart', - args, - workingDirectory: Directory.current.path, - ); - - final golden = File('test/testdata/dartdoc_test.txt'); - golden - ..createSync(recursive: true) - ..writeAsStringSync(process.stdout.toString()); - }); - - test('run dartdoc_test in example directory', () async { final directory = p.join(Directory.current.path, 'example'); final process = await Process.run( 'dart', @@ -64,7 +44,7 @@ void main() { workingDirectory: directory, ); - final golden = File('test/testdata/dartdoc_test_example.txt'); + final golden = File('test/testdata/dartdoc_test.txt'); golden ..createSync(recursive: true) ..writeAsString(process.stdout.toString()); @@ -92,10 +72,11 @@ void testWithGolden(String name, List args) { Future execute(List args) { return TestProcess.start( Platform.resolvedExecutable, - ['bin/dartdoc_test.dart', ...args], + ['run', 'dartdoc_test', ...args], + workingDirectory: 'example', ); } String _formatCommand(List args) { - return '\$ dart run bin/dartdoc_test.dart ${args.join(' ')}'; + return '\$ dart run dartdoc_test ${args.join(' ')}'; } diff --git a/dartdoc_test/test/testdata/codeSample/error_example_0.dart b/dartdoc_test/test/testdata/codeSample/error_example_0.dart index 65dc0e90..f6601413 100644 --- a/dartdoc_test/test/testdata/codeSample/error_example_0.dart +++ b/dartdoc_test/test/testdata/codeSample/error_example_0.dart @@ -1,5 +1,5 @@ -import '../../../example/lib/error_example.dart'; +import 'package:example/error_example.dart'; void main() { final fact = factorial(5) diff --git a/dartdoc_test/test/testdata/codeSample/error_example_1.dart b/dartdoc_test/test/testdata/codeSample/error_example_1.dart index 70691161..9d9afded 100644 --- a/dartdoc_test/test/testdata/codeSample/error_example_1.dart +++ b/dartdoc_test/test/testdata/codeSample/error_example_1.dart @@ -1,5 +1,5 @@ -import '../../../example/lib/error_example.dart'; +import 'package:example/error_example.dart'; void main() { final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); diff --git a/dartdoc_test/test/testdata/codeSample/error_example_2.dart b/dartdoc_test/test/testdata/codeSample/error_example_2.dart index 9f98bf5d..05f0c310 100644 --- a/dartdoc_test/test/testdata/codeSample/error_example_2.dart +++ b/dartdoc_test/test/testdata/codeSample/error_example_2.dart @@ -1,5 +1,5 @@ -import '../../../example/lib/error_example.dart'; +import 'package:example/error_example.dart'; void main() { final gcd = gcd(48, 18); diff --git a/dartdoc_test/test/testdata/codeSample/error_example_3.dart b/dartdoc_test/test/testdata/codeSample/error_example_3.dart index 2f1a97cb..1c9070cb 100644 --- a/dartdoc_test/test/testdata/codeSample/error_example_3.dart +++ b/dartdoc_test/test/testdata/codeSample/error_example_3.dart @@ -1,5 +1,5 @@ -import '../../../example/lib/error_example.dart'; +import 'package:example/error_example.dart'; void main() { final length = 5.length; diff --git a/dartdoc_test/test/testdata/codeSample/example_0.dart b/dartdoc_test/test/testdata/codeSample/example_0.dart index f31c3306..50084745 100644 --- a/dartdoc_test/test/testdata/codeSample/example_0.dart +++ b/dartdoc_test/test/testdata/codeSample/example_0.dart @@ -1,5 +1,5 @@ import 'dart:convert'; -import '../../../example/lib/example.dart'; +import 'package:example/example.dart'; void main() { final result = add(2, 3); diff --git a/dartdoc_test/test/testdata/codeSample/example_1.dart b/dartdoc_test/test/testdata/codeSample/example_1.dart index 1352371c..ddf00e60 100644 --- a/dartdoc_test/test/testdata/codeSample/example_1.dart +++ b/dartdoc_test/test/testdata/codeSample/example_1.dart @@ -1,5 +1,5 @@ import 'dart:convert'; -import '../../../example/lib/example.dart'; +import 'package:example/example.dart'; void main() { final result = subtract(5, 3); diff --git a/dartdoc_test/test/testdata/codeSample/example_2.dart b/dartdoc_test/test/testdata/codeSample/example_2.dart index c1c70d4d..ca471761 100644 --- a/dartdoc_test/test/testdata/codeSample/example_2.dart +++ b/dartdoc_test/test/testdata/codeSample/example_2.dart @@ -1,5 +1,5 @@ import 'dart:convert'; -import '../../../example/lib/example.dart'; +import 'package:example/example.dart'; void main() { final result = multiply(4, 5); diff --git a/dartdoc_test/test/testdata/codeSample/example_3.dart b/dartdoc_test/test/testdata/codeSample/example_3.dart index 519fe1ea..1d82a2d9 100644 --- a/dartdoc_test/test/testdata/codeSample/example_3.dart +++ b/dartdoc_test/test/testdata/codeSample/example_3.dart @@ -1,5 +1,5 @@ import 'dart:convert'; -import '../../../example/lib/example.dart'; +import 'package:example/example.dart'; void main() { final result = multiply(6, 7); diff --git a/dartdoc_test/test/testdata/codeSample/extractor_0.dart b/dartdoc_test/test/testdata/codeSample/extractor_0.dart deleted file mode 100644 index 4784c2a8..00000000 --- a/dartdoc_test/test/testdata/codeSample/extractor_0.dart +++ /dev/null @@ -1,14 +0,0 @@ -import 'dart:convert'; -import 'dart:io'; -import 'package:path/path.dart' as p; -import 'package:analyzer/dart/analysis/results.dart'; -import 'package:analyzer/dart/ast/ast.dart'; -import 'package:analyzer/dart/ast/visitor.dart'; -import 'package:markdown/markdown.dart'; -import 'package:source_span/source_span.dart'; -import 'package:dartdoc_test/src/extractor.dart'; - -void main() { - final comment = ' /// some comment\n'; - print(stripleadingWhiteSpace(comment)); // ['/// some comment'] -} diff --git a/dartdoc_test/test/testdata/codeSample/extractor_1.dart b/dartdoc_test/test/testdata/codeSample/extractor_1.dart deleted file mode 100644 index 9a486b68..00000000 --- a/dartdoc_test/test/testdata/codeSample/extractor_1.dart +++ /dev/null @@ -1,14 +0,0 @@ -import 'dart:convert'; -import 'dart:io'; -import 'package:path/path.dart' as p; -import 'package:analyzer/dart/analysis/results.dart'; -import 'package:analyzer/dart/ast/ast.dart'; -import 'package:analyzer/dart/ast/visitor.dart'; -import 'package:markdown/markdown.dart'; -import 'package:source_span/source_span.dart'; -import 'package:dartdoc_test/src/extractor.dart'; - -void main() { - final comment1 = '/// some comment'; - print(stripComments(comment1)); // 'some comment' -} diff --git a/dartdoc_test/test/testdata/codeSample/extractor_2.dart b/dartdoc_test/test/testdata/codeSample/extractor_2.dart deleted file mode 100644 index 6d065e86..00000000 --- a/dartdoc_test/test/testdata/codeSample/extractor_2.dart +++ /dev/null @@ -1,17 +0,0 @@ -import 'dart:convert'; -import 'dart:io'; -import 'package:path/path.dart' as p; -import 'package:analyzer/dart/analysis/results.dart'; -import 'package:analyzer/dart/ast/ast.dart'; -import 'package:analyzer/dart/ast/visitor.dart'; -import 'package:markdown/markdown.dart'; -import 'package:source_span/source_span.dart'; -import 'package:dartdoc_test/src/extractor.dart'; - -void main() { - final comment2 = ''' - /** - * some comment - */'''; - stripComments(comment2); // 'some comment' -} diff --git a/dartdoc_test/test/testdata/dartdoc_test.txt b/dartdoc_test/test/testdata/dartdoc_test.txt index 85b64012..fe4dce31 100644 --- a/dartdoc_test/test/testdata/dartdoc_test.txt +++ b/dartdoc_test/test/testdata/dartdoc_test.txt @@ -1,9 +1,9 @@ -00:00 +0: loading example/test/dartdoc_test.dart +00:00 +0: loading test/dartdoc_test.dart Extracting code samples ... Analyzing code samples ... -00:00 +0: [dartdoc_test] example/lib/error_example.dart test for ) -00:00 +0 -1: [dartdoc_test] example/lib/error_example.dart test for ) [E] - example/lib/error_example.dart:17:29: : Expected to find ';'. +00:00 +0: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for ) +00:00 +0 -1: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for ) [E] + package:example/error_example.dart:17:29: : Expected to find ';'. ╷ 17 │ /// final fact = factorial(5) │ ^ @@ -11,9 +11,9 @@ Analyzing code samples ... package:matcher fail package:dartdoc_test/src/reporter.dart 141:13 _RepoterForTest._reportIssue. -00:00 +0 -1: [dartdoc_test] example/lib/error_example.dart test for isPalindrome -00:00 +0 -2: [dartdoc_test] example/lib/error_example.dart test for isPalindrome [E] - example/lib/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. +00:00 +0 -1: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for isPalindrome +00:00 +0 -2: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for isPalindrome [E] + package:example/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. ╷ 31 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); │ ^^^^^^^^^^^^ @@ -21,9 +21,9 @@ Analyzing code samples ... package:matcher fail package:dartdoc_test/src/reporter.dart 141:13 _RepoterForTest._reportIssue. -00:00 +0 -2: [dartdoc_test] example/lib/error_example.dart test for gcd -00:00 +0 -3: [dartdoc_test] example/lib/error_example.dart test for gcd [E] - example/lib/error_example.dart:39:36: : Local variable 'gcd' can't be referenced before it is declared. +00:00 +0 -2: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for gcd +00:00 +0 -3: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for gcd [E] + package:example/error_example.dart:39:36: : Local variable 'gcd' can't be referenced before it is declared. ╷ 39 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. │ ^^^ @@ -31,9 +31,9 @@ Analyzing code samples ... package:matcher fail package:dartdoc_test/src/reporter.dart 141:13 _RepoterForTest._reportIssue. -00:00 +0 -3: [dartdoc_test] example/lib/error_example.dart test for length -00:00 +0 -4: [dartdoc_test] example/lib/error_example.dart test for length [E] - example/lib/error_example.dart:53:32: : The getter 'length' isn't defined for the type 'int'. +00:00 +0 -3: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for length +00:00 +0 -4: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for length [E] + package:example/error_example.dart:53:32: : The getter 'length' isn't defined for the type 'int'. ╷ 53 │ /// Should return: The getter 'length' isn't defined for the class 'int'. │ ^^^^^^ diff --git a/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt b/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt index 1b0844a2..4538b768 100644 --- a/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt +++ b/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt @@ -1,63 +1,39 @@ -$ dart run bin/dartdoc_test.dart -v +$ dart run dartdoc_test -v Extracting code samples ... Analyzing code samples ... original error: .dartdoc_test/error_example_0.dart:5:27: Expected to find ';'. -example/lib/error_example.dart:17:29: : Expected to find ';'. +package:example/error_example.dart:17:29: : Expected to find ';'. ╷ 17 │ /// final fact = factorial(5) │ ^ ╵ original error: .dartdoc_test/error_example_1.dart:5:24: Local variable 'isPalindrome' can't be referenced before it is declared. -example/lib/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. +package:example/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. ╷ 31 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); │ ^^^^^^^^^^^^ ╵ -.dartdoc_test/error_example_1.dart:2:8: Unused import: '../example/lib/error_example.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/error_example_1.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) original error: .dartdoc_test/error_example_2.dart:5:15: Local variable 'gcd' can't be referenced before it is declared. -example/lib/error_example.dart:39:36: : Local variable 'gcd' can't be referenced before it is declared. +package:example/error_example.dart:39:36: : Local variable 'gcd' can't be referenced before it is declared. ╷ 39 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. │ ^^^ ╵ -.dartdoc_test/error_example_2.dart:2:8: Unused import: '../example/lib/error_example.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/error_example_2.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) original error: .dartdoc_test/error_example_3.dart:5:20: The getter 'length' isn't defined for the type 'int'. -example/lib/error_example.dart:53:32: : The getter 'length' isn't defined for the type 'int'. +package:example/error_example.dart:53:32: : The getter 'length' isn't defined for the type 'int'. ╷ 53 │ /// Should return: The getter 'length' isn't defined for the class 'int'. │ ^^^^^^ ╵ -.dartdoc_test/error_example_3.dart:2:8: Unused import: '../example/lib/error_example.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/error_example_3.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) .dartdoc_test/example_0.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) .dartdoc_test/example_1.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) .dartdoc_test/example_2.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) .dartdoc_test/example_3.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_0.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_0.dart:2:8: Unused import: 'dart:io'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_0.dart:3:8: Unused import: 'package:path/path.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_0.dart:4:8: Unused import: 'package:analyzer/dart/analysis/results.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_0.dart:5:8: Unused import: 'package:analyzer/dart/ast/ast.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_0.dart:6:8: Unused import: 'package:analyzer/dart/ast/visitor.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_0.dart:7:8: Unused import: 'package:markdown/markdown.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_0.dart:8:8: Unused import: 'package:source_span/source_span.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_1.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_1.dart:2:8: Unused import: 'dart:io'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_1.dart:3:8: Unused import: 'package:path/path.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_1.dart:4:8: Unused import: 'package:analyzer/dart/analysis/results.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_1.dart:5:8: Unused import: 'package:analyzer/dart/ast/ast.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_1.dart:6:8: Unused import: 'package:analyzer/dart/ast/visitor.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_1.dart:7:8: Unused import: 'package:markdown/markdown.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_1.dart:8:8: Unused import: 'package:source_span/source_span.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_2.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_2.dart:2:8: Unused import: 'dart:io'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_2.dart:3:8: Unused import: 'package:path/path.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_2.dart:4:8: Unused import: 'package:analyzer/dart/analysis/results.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_2.dart:5:8: Unused import: 'package:analyzer/dart/ast/ast.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_2.dart:6:8: Unused import: 'package:analyzer/dart/ast/visitor.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_2.dart:7:8: Unused import: 'package:markdown/markdown.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_2.dart:8:8: Unused import: 'package:source_span/source_span.dart'. (ignored because issue occurs in the generated code) -FAILED: 4 issues found (Found 11 code samples in 3 files) \ No newline at end of file +FAILED: 4 issues found (Found 8 code samples in 2 files) \ No newline at end of file diff --git a/dartdoc_test/test/testdata/run analyze command by default.txt b/dartdoc_test/test/testdata/run analyze command by default.txt index 98ba2845..1bee1ef5 100644 --- a/dartdoc_test/test/testdata/run analyze command by default.txt +++ b/dartdoc_test/test/testdata/run analyze command by default.txt @@ -1,28 +1,28 @@ -$ dart run bin/dartdoc_test.dart +$ dart run dartdoc_test Extracting code samples ... Analyzing code samples ... -example/lib/error_example.dart:17:29: : Expected to find ';'. +package:example/error_example.dart:17:29: : Expected to find ';'. ╷ 17 │ /// final fact = factorial(5) │ ^ ╵ -example/lib/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. +package:example/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. ╷ 31 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); │ ^^^^^^^^^^^^ ╵ -example/lib/error_example.dart:39:36: : Local variable 'gcd' can't be referenced before it is declared. +package:example/error_example.dart:39:36: : Local variable 'gcd' can't be referenced before it is declared. ╷ 39 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. │ ^^^ ╵ -example/lib/error_example.dart:53:32: : The getter 'length' isn't defined for the type 'int'. +package:example/error_example.dart:53:32: : The getter 'length' isn't defined for the type 'int'. ╷ 53 │ /// Should return: The getter 'length' isn't defined for the class 'int'. │ ^^^^^^ ╵ -FAILED: 4 issues found (Found 11 code samples in 3 files) \ No newline at end of file +FAILED: 4 issues found (Found 8 code samples in 2 files) \ No newline at end of file diff --git a/dartdoc_test/test/testdata/run analyze command with exclude option.txt b/dartdoc_test/test/testdata/run analyze command with exclude option.txt index dab5d5d0..c2318aa9 100644 --- a/dartdoc_test/test/testdata/run analyze command with exclude option.txt +++ b/dartdoc_test/test/testdata/run analyze command with exclude option.txt @@ -1,28 +1,5 @@ -$ dart run bin/dartdoc_test.dart analyze -x lib/** +$ dart run dartdoc_test analyze -x lib/** Extracting code samples ... Analyzing code samples ... -example/lib/error_example.dart:17:29: : Expected to find ';'. - ╷ -17 │ /// final fact = factorial(5) - │ ^ - ╵ - -example/lib/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. - ╷ -31 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); - │ ^^^^^^^^^^^^ - ╵ - -example/lib/error_example.dart:39:36: : Local variable 'gcd' can't be referenced before it is declared. - ╷ -39 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. - │ ^^^ - ╵ - -example/lib/error_example.dart:53:32: : The getter 'length' isn't defined for the type 'int'. - ╷ -53 │ /// Should return: The getter 'length' isn't defined for the class 'int'. - │ ^^^^^^ - ╵ - -FAILED: 4 issues found (Found 8 code samples in 2 files) \ No newline at end of file +No issues found. +PASSED: No issues found! (Found 0 code samples in 0 files) \ No newline at end of file diff --git a/dartdoc_test/test/testdata/run analyze command with verbose flag.txt b/dartdoc_test/test/testdata/run analyze command with verbose flag.txt index a90b2199..a09cfd70 100644 --- a/dartdoc_test/test/testdata/run analyze command with verbose flag.txt +++ b/dartdoc_test/test/testdata/run analyze command with verbose flag.txt @@ -1,63 +1,39 @@ -$ dart run bin/dartdoc_test.dart analyze -v +$ dart run dartdoc_test analyze -v Extracting code samples ... Analyzing code samples ... original error: .dartdoc_test/error_example_0.dart:5:27: Expected to find ';'. -example/lib/error_example.dart:17:29: : Expected to find ';'. +package:example/error_example.dart:17:29: : Expected to find ';'. ╷ 17 │ /// final fact = factorial(5) │ ^ ╵ original error: .dartdoc_test/error_example_1.dart:5:24: Local variable 'isPalindrome' can't be referenced before it is declared. -example/lib/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. +package:example/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. ╷ 31 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); │ ^^^^^^^^^^^^ ╵ -.dartdoc_test/error_example_1.dart:2:8: Unused import: '../example/lib/error_example.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/error_example_1.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) original error: .dartdoc_test/error_example_2.dart:5:15: Local variable 'gcd' can't be referenced before it is declared. -example/lib/error_example.dart:39:36: : Local variable 'gcd' can't be referenced before it is declared. +package:example/error_example.dart:39:36: : Local variable 'gcd' can't be referenced before it is declared. ╷ 39 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. │ ^^^ ╵ -.dartdoc_test/error_example_2.dart:2:8: Unused import: '../example/lib/error_example.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/error_example_2.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) original error: .dartdoc_test/error_example_3.dart:5:20: The getter 'length' isn't defined for the type 'int'. -example/lib/error_example.dart:53:32: : The getter 'length' isn't defined for the type 'int'. +package:example/error_example.dart:53:32: : The getter 'length' isn't defined for the type 'int'. ╷ 53 │ /// Should return: The getter 'length' isn't defined for the class 'int'. │ ^^^^^^ ╵ -.dartdoc_test/error_example_3.dart:2:8: Unused import: '../example/lib/error_example.dart'. (ignored because issue occurs in the generated code) +.dartdoc_test/error_example_3.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) .dartdoc_test/example_0.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) .dartdoc_test/example_1.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) .dartdoc_test/example_2.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) .dartdoc_test/example_3.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_0.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_0.dart:2:8: Unused import: 'dart:io'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_0.dart:3:8: Unused import: 'package:path/path.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_0.dart:4:8: Unused import: 'package:analyzer/dart/analysis/results.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_0.dart:5:8: Unused import: 'package:analyzer/dart/ast/ast.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_0.dart:6:8: Unused import: 'package:analyzer/dart/ast/visitor.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_0.dart:7:8: Unused import: 'package:markdown/markdown.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_0.dart:8:8: Unused import: 'package:source_span/source_span.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_1.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_1.dart:2:8: Unused import: 'dart:io'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_1.dart:3:8: Unused import: 'package:path/path.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_1.dart:4:8: Unused import: 'package:analyzer/dart/analysis/results.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_1.dart:5:8: Unused import: 'package:analyzer/dart/ast/ast.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_1.dart:6:8: Unused import: 'package:analyzer/dart/ast/visitor.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_1.dart:7:8: Unused import: 'package:markdown/markdown.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_1.dart:8:8: Unused import: 'package:source_span/source_span.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_2.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_2.dart:2:8: Unused import: 'dart:io'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_2.dart:3:8: Unused import: 'package:path/path.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_2.dart:4:8: Unused import: 'package:analyzer/dart/analysis/results.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_2.dart:5:8: Unused import: 'package:analyzer/dart/ast/ast.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_2.dart:6:8: Unused import: 'package:analyzer/dart/ast/visitor.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_2.dart:7:8: Unused import: 'package:markdown/markdown.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/extractor_2.dart:8:8: Unused import: 'package:source_span/source_span.dart'. (ignored because issue occurs in the generated code) -FAILED: 4 issues found (Found 11 code samples in 3 files) \ No newline at end of file +FAILED: 4 issues found (Found 8 code samples in 2 files) \ No newline at end of file diff --git a/dartdoc_test/test/testdata/run analyze command.txt b/dartdoc_test/test/testdata/run analyze command.txt index 8ccf3476..6f8f9cc1 100644 --- a/dartdoc_test/test/testdata/run analyze command.txt +++ b/dartdoc_test/test/testdata/run analyze command.txt @@ -1,28 +1,28 @@ -$ dart run bin/dartdoc_test.dart analyze +$ dart run dartdoc_test analyze Extracting code samples ... Analyzing code samples ... -example/lib/error_example.dart:17:29: : Expected to find ';'. +package:example/error_example.dart:17:29: : Expected to find ';'. ╷ 17 │ /// final fact = factorial(5) │ ^ ╵ -example/lib/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. +package:example/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. ╷ 31 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); │ ^^^^^^^^^^^^ ╵ -example/lib/error_example.dart:39:36: : Local variable 'gcd' can't be referenced before it is declared. +package:example/error_example.dart:39:36: : Local variable 'gcd' can't be referenced before it is declared. ╷ 39 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. │ ^^^ ╵ -example/lib/error_example.dart:53:32: : The getter 'length' isn't defined for the type 'int'. +package:example/error_example.dart:53:32: : The getter 'length' isn't defined for the type 'int'. ╷ 53 │ /// Should return: The getter 'length' isn't defined for the class 'int'. │ ^^^^^^ ╵ -FAILED: 4 issues found (Found 11 code samples in 3 files) \ No newline at end of file +FAILED: 4 issues found (Found 8 code samples in 2 files) \ No newline at end of file diff --git a/dartdoc_test/test/testdata/show help.txt b/dartdoc_test/test/testdata/show help.txt index 78fbd7a2..c76c0e73 100644 --- a/dartdoc_test/test/testdata/show help.txt +++ b/dartdoc_test/test/testdata/show help.txt @@ -1,4 +1,4 @@ -$ dart run bin/dartdoc_test.dart -h +$ dart run dartdoc_test -h A tool to extract and analyze code samples in Dart projects. Usage: dartdoc_test [arguments] From 40386b0a5c975faadc0b681741f02cb40cf7f84a Mon Sep 17 00:00:00 2001 From: takumma Date: Mon, 12 Aug 2024 18:55:36 +0900 Subject: [PATCH 09/23] do not wrap code samples with main() when code sample includes main() --- dartdoc_test/example/lib/example.dart | 37 +++++++++++++++++-- dartdoc_test/lib/src/model.dart | 5 +-- .../test/testdata/codeSample/example_0.dart | 2 +- .../test/testdata/codeSample/example_1.dart | 2 +- .../test/testdata/codeSample/example_2.dart | 2 +- .../test/testdata/codeSample/example_3.dart | 2 +- .../test/testdata/codeSample/example_5.dart | 7 ++++ .../test/testdata/codeSample/example_6.dart | 9 +++++ ...e command by default with verbose flag.txt | 10 ++--- .../run analyze command by default.txt | 2 +- .../run analyze command with verbose flag.txt | 10 ++--- .../test/testdata/run analyze command.txt | 2 +- 12 files changed, 67 insertions(+), 23 deletions(-) create mode 100644 dartdoc_test/test/testdata/codeSample/example_5.dart create mode 100644 dartdoc_test/test/testdata/codeSample/example_6.dart diff --git a/dartdoc_test/example/lib/example.dart b/dartdoc_test/example/lib/example.dart index b90ed26c..a80c1888 100644 --- a/dartdoc_test/example/lib/example.dart +++ b/dartdoc_test/example/lib/example.dart @@ -12,10 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. -import 'dart:convert'; - -/// Example of documentation comments and code samples in Dart. - +/// Examples of documentation comments and code samples in Dart. +/// /// Dart code block will be analyzed by dartdoc_test. /// /// ```dart @@ -72,3 +70,34 @@ void ignore() {} /// tagIgnore() // it is not reported. /// ``` void tagIgnore() {} + +/// by default, code samples will be wrapped by `main()` function and analyzed. +/// However, If code sample has `main()` function, it will be not wrapped by `main()` +/// function and analyzed as it is. +/// +/// ```dart +/// void main() { +/// final result = divide(10, 2); +/// print(result); // 5 +/// } +/// ``` +int divide(int x, int y) { + return x ~/ y; +} + +/// When dartdoc_test analyze the code sample, it uses the imports of the file +/// where the code sample is located by default. +/// Also, you can import some libraries and use them in code samples. +/// but you need to add main() function to run the code when you add imports customly. +/// +/// ```dart +/// import 'dart:convert'; +/// +/// void main() { +/// final x = LineSplitter().convert('2\n3').map(int.parse).toList(); +/// print(pow(x[0], x[1])); // 8 +/// } +/// ``` +int pow(int x, int y) { + return x ^ y; +} diff --git a/dartdoc_test/lib/src/model.dart b/dartdoc_test/lib/src/model.dart index 490b70ee..0cc1cd4b 100644 --- a/dartdoc_test/lib/src/model.dart +++ b/dartdoc_test/lib/src/model.dart @@ -74,7 +74,6 @@ class DocumentationCodeSample { bool get ignore => code.contains('// dartdoc_test:ignore_error'); bool get hasMain => code.contains('void main()'); - bool get hasImport => code.contains('import '); /// Create a sample by wrapping the code with a main function and imports. String wrappedCode(Directory testDir) { @@ -92,10 +91,10 @@ class DocumentationCodeSample { } } buf.writeln(); - buf.writeln('void main() {'); + if (!hasMain) buf.writeln('void main() {'); buf.writeAll(LineSplitter.split(code).map((l) => ' $l'), '\n'); buf.writeln(); - buf.writeln('}'); + if (!hasMain) buf.writeln('}'); return buf.toString(); } } diff --git a/dartdoc_test/test/testdata/codeSample/example_0.dart b/dartdoc_test/test/testdata/codeSample/example_0.dart index 50084745..94dedae7 100644 --- a/dartdoc_test/test/testdata/codeSample/example_0.dart +++ b/dartdoc_test/test/testdata/codeSample/example_0.dart @@ -1,4 +1,4 @@ -import 'dart:convert'; + import 'package:example/example.dart'; void main() { diff --git a/dartdoc_test/test/testdata/codeSample/example_1.dart b/dartdoc_test/test/testdata/codeSample/example_1.dart index ddf00e60..40fa4b5c 100644 --- a/dartdoc_test/test/testdata/codeSample/example_1.dart +++ b/dartdoc_test/test/testdata/codeSample/example_1.dart @@ -1,4 +1,4 @@ -import 'dart:convert'; + import 'package:example/example.dart'; void main() { diff --git a/dartdoc_test/test/testdata/codeSample/example_2.dart b/dartdoc_test/test/testdata/codeSample/example_2.dart index ca471761..c4324621 100644 --- a/dartdoc_test/test/testdata/codeSample/example_2.dart +++ b/dartdoc_test/test/testdata/codeSample/example_2.dart @@ -1,4 +1,4 @@ -import 'dart:convert'; + import 'package:example/example.dart'; void main() { diff --git a/dartdoc_test/test/testdata/codeSample/example_3.dart b/dartdoc_test/test/testdata/codeSample/example_3.dart index 1d82a2d9..6ef62d04 100644 --- a/dartdoc_test/test/testdata/codeSample/example_3.dart +++ b/dartdoc_test/test/testdata/codeSample/example_3.dart @@ -1,4 +1,4 @@ -import 'dart:convert'; + import 'package:example/example.dart'; void main() { diff --git a/dartdoc_test/test/testdata/codeSample/example_5.dart b/dartdoc_test/test/testdata/codeSample/example_5.dart new file mode 100644 index 00000000..32878d87 --- /dev/null +++ b/dartdoc_test/test/testdata/codeSample/example_5.dart @@ -0,0 +1,7 @@ + +import 'package:example/example.dart'; + + void main() { + final result = divide(10, 2); + print(result); // 5 + } diff --git a/dartdoc_test/test/testdata/codeSample/example_6.dart b/dartdoc_test/test/testdata/codeSample/example_6.dart new file mode 100644 index 00000000..57997e4f --- /dev/null +++ b/dartdoc_test/test/testdata/codeSample/example_6.dart @@ -0,0 +1,9 @@ + +import 'package:example/example.dart'; + + import 'dart:convert'; + + void main() { + final x = LineSplitter().convert('2\n3').map(int.parse).toList(); + print(pow(x[0], x[1])); // 8 + } diff --git a/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt b/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt index 4538b768..d59452d6 100644 --- a/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt +++ b/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt @@ -32,8 +32,8 @@ package:example/error_example.dart:53:32: : The getter 'length' isn't defined fo ╵ .dartdoc_test/error_example_3.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_0.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_1.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_2.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_3.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -FAILED: 4 issues found (Found 8 code samples in 2 files) \ No newline at end of file +.dartdoc_test/example_0.dart:2:7: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/example_1.dart:2:7: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/example_2.dart:2:7: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/example_3.dart:2:7: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +FAILED: 4 issues found (Found 10 code samples in 2 files) \ No newline at end of file diff --git a/dartdoc_test/test/testdata/run analyze command by default.txt b/dartdoc_test/test/testdata/run analyze command by default.txt index 1bee1ef5..5bd5002a 100644 --- a/dartdoc_test/test/testdata/run analyze command by default.txt +++ b/dartdoc_test/test/testdata/run analyze command by default.txt @@ -25,4 +25,4 @@ package:example/error_example.dart:53:32: : The getter 'length' isn't defined fo │ ^^^^^^ ╵ -FAILED: 4 issues found (Found 8 code samples in 2 files) \ No newline at end of file +FAILED: 4 issues found (Found 10 code samples in 2 files) \ No newline at end of file diff --git a/dartdoc_test/test/testdata/run analyze command with verbose flag.txt b/dartdoc_test/test/testdata/run analyze command with verbose flag.txt index a09cfd70..56e37011 100644 --- a/dartdoc_test/test/testdata/run analyze command with verbose flag.txt +++ b/dartdoc_test/test/testdata/run analyze command with verbose flag.txt @@ -32,8 +32,8 @@ package:example/error_example.dart:53:32: : The getter 'length' isn't defined fo ╵ .dartdoc_test/error_example_3.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_0.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_1.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_2.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_3.dart:1:8: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -FAILED: 4 issues found (Found 8 code samples in 2 files) \ No newline at end of file +.dartdoc_test/example_0.dart:2:7: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/example_1.dart:2:7: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/example_2.dart:2:7: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dartdoc_test/example_3.dart:2:7: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +FAILED: 4 issues found (Found 10 code samples in 2 files) \ No newline at end of file diff --git a/dartdoc_test/test/testdata/run analyze command.txt b/dartdoc_test/test/testdata/run analyze command.txt index 6f8f9cc1..e21e9ca5 100644 --- a/dartdoc_test/test/testdata/run analyze command.txt +++ b/dartdoc_test/test/testdata/run analyze command.txt @@ -25,4 +25,4 @@ package:example/error_example.dart:53:32: : The getter 'length' isn't defined fo │ ^^^^^^ ╵ -FAILED: 4 issues found (Found 8 code samples in 2 files) \ No newline at end of file +FAILED: 4 issues found (Found 10 code samples in 2 files) \ No newline at end of file From 882fa80eb85172f345abb467bf8de90efbd8c7a5 Mon Sep 17 00:00:00 2001 From: takumma Date: Mon, 12 Aug 2024 19:28:25 +0900 Subject: [PATCH 10/23] fix --- .../test/testdata/dartdoc_test_example.txt | 47 ------------------- 1 file changed, 47 deletions(-) delete mode 100644 dartdoc_test/test/testdata/dartdoc_test_example.txt diff --git a/dartdoc_test/test/testdata/dartdoc_test_example.txt b/dartdoc_test/test/testdata/dartdoc_test_example.txt deleted file mode 100644 index fe4dce31..00000000 --- a/dartdoc_test/test/testdata/dartdoc_test_example.txt +++ /dev/null @@ -1,47 +0,0 @@ -00:00 +0: loading test/dartdoc_test.dart -Extracting code samples ... -Analyzing code samples ... -00:00 +0: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for ) -00:00 +0 -1: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for ) [E] - package:example/error_example.dart:17:29: : Expected to find ';'. - ╷ - 17 │ /// final fact = factorial(5) - │ ^ - ╵ - package:matcher fail - package:dartdoc_test/src/reporter.dart 141:13 _RepoterForTest._reportIssue. - -00:00 +0 -1: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for isPalindrome -00:00 +0 -2: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for isPalindrome [E] - package:example/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. - ╷ - 31 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); - │ ^^^^^^^^^^^^ - ╵ - package:matcher fail - package:dartdoc_test/src/reporter.dart 141:13 _RepoterForTest._reportIssue. - -00:00 +0 -2: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for gcd -00:00 +0 -3: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for gcd [E] - package:example/error_example.dart:39:36: : Local variable 'gcd' can't be referenced before it is declared. - ╷ - 39 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. - │ ^^^ - ╵ - package:matcher fail - package:dartdoc_test/src/reporter.dart 141:13 _RepoterForTest._reportIssue. - -00:00 +0 -3: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for length -00:00 +0 -4: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for length [E] - package:example/error_example.dart:53:32: : The getter 'length' isn't defined for the type 'int'. - ╷ - 53 │ /// Should return: The getter 'length' isn't defined for the class 'int'. - │ ^^^^^^ - ╵ - package:matcher fail - package:dartdoc_test/src/reporter.dart 141:13 _RepoterForTest._reportIssue. - -00:00 +0 -4: Some tests failed. - -Consider enabling the flag chain-stack-traces to receive more detailed exceptions. -For example, 'dart test --chain-stack-traces'. From e0a8f0208aab9483977118d3dcf23438b41aa0f8 Mon Sep 17 00:00:00 2001 From: takumma Date: Tue, 13 Aug 2024 21:30:10 +0900 Subject: [PATCH 11/23] rename code sample output directory --- dartdoc_test/README.md | 2 +- dartdoc_test/test/integration_test.dart | 6 ++---- .../{codeSample => code_sample}/error_example_0.dart | 0 .../{codeSample => code_sample}/error_example_1.dart | 0 .../{codeSample => code_sample}/error_example_2.dart | 0 .../{codeSample => code_sample}/error_example_3.dart | 0 .../testdata/{codeSample => code_sample}/example_0.dart | 0 .../testdata/{codeSample => code_sample}/example_1.dart | 0 .../testdata/{codeSample => code_sample}/example_2.dart | 0 .../testdata/{codeSample => code_sample}/example_3.dart | 0 .../testdata/{codeSample => code_sample}/example_5.dart | 0 .../testdata/{codeSample => code_sample}/example_6.dart | 0 12 files changed, 3 insertions(+), 5 deletions(-) rename dartdoc_test/test/testdata/{codeSample => code_sample}/error_example_0.dart (100%) rename dartdoc_test/test/testdata/{codeSample => code_sample}/error_example_1.dart (100%) rename dartdoc_test/test/testdata/{codeSample => code_sample}/error_example_2.dart (100%) rename dartdoc_test/test/testdata/{codeSample => code_sample}/error_example_3.dart (100%) rename dartdoc_test/test/testdata/{codeSample => code_sample}/example_0.dart (100%) rename dartdoc_test/test/testdata/{codeSample => code_sample}/example_1.dart (100%) rename dartdoc_test/test/testdata/{codeSample => code_sample}/example_2.dart (100%) rename dartdoc_test/test/testdata/{codeSample => code_sample}/example_3.dart (100%) rename dartdoc_test/test/testdata/{codeSample => code_sample}/example_5.dart (100%) rename dartdoc_test/test/testdata/{codeSample => code_sample}/example_6.dart (100%) diff --git a/dartdoc_test/README.md b/dartdoc_test/README.md index 818a8ec9..56c04742 100644 --- a/dartdoc_test/README.md +++ b/dartdoc_test/README.md @@ -20,7 +20,7 @@ Therefore, `dartdoc_test` provides a way to analyze code samples in documentatio dart pub add dev:dartdoc_test # Run dartdoc_test directly -dart run dartdoc_test analyze +dart run dartdoc_test ``` # Using in test diff --git a/dartdoc_test/test/integration_test.dart b/dartdoc_test/test/integration_test.dart index 17ca1eba..2ff9864c 100644 --- a/dartdoc_test/test/integration_test.dart +++ b/dartdoc_test/test/integration_test.dart @@ -29,8 +29,8 @@ void main() { group('extractor', () { test('extract code samples in example directory', () async { - final process = - await execute(['analyze', '-w', '-o', '../test/testdata/codeSample']); + final process = await execute( + ['analyze', '-w', '-o', '../test/testdata/code_sample']); await process.shouldExit(0); }); }); @@ -53,10 +53,8 @@ void main() { } void testWithGolden(String name, List args) { - const separator = '======== separator ========\n'; // TODO: use separator final golden = File('test/testdata/$name.txt'); test('integration_test: $name', () async { - // run name in command line final buf = StringBuffer(); buf.writeln(_formatCommand(args)); final process = await execute(args); diff --git a/dartdoc_test/test/testdata/codeSample/error_example_0.dart b/dartdoc_test/test/testdata/code_sample/error_example_0.dart similarity index 100% rename from dartdoc_test/test/testdata/codeSample/error_example_0.dart rename to dartdoc_test/test/testdata/code_sample/error_example_0.dart diff --git a/dartdoc_test/test/testdata/codeSample/error_example_1.dart b/dartdoc_test/test/testdata/code_sample/error_example_1.dart similarity index 100% rename from dartdoc_test/test/testdata/codeSample/error_example_1.dart rename to dartdoc_test/test/testdata/code_sample/error_example_1.dart diff --git a/dartdoc_test/test/testdata/codeSample/error_example_2.dart b/dartdoc_test/test/testdata/code_sample/error_example_2.dart similarity index 100% rename from dartdoc_test/test/testdata/codeSample/error_example_2.dart rename to dartdoc_test/test/testdata/code_sample/error_example_2.dart diff --git a/dartdoc_test/test/testdata/codeSample/error_example_3.dart b/dartdoc_test/test/testdata/code_sample/error_example_3.dart similarity index 100% rename from dartdoc_test/test/testdata/codeSample/error_example_3.dart rename to dartdoc_test/test/testdata/code_sample/error_example_3.dart diff --git a/dartdoc_test/test/testdata/codeSample/example_0.dart b/dartdoc_test/test/testdata/code_sample/example_0.dart similarity index 100% rename from dartdoc_test/test/testdata/codeSample/example_0.dart rename to dartdoc_test/test/testdata/code_sample/example_0.dart diff --git a/dartdoc_test/test/testdata/codeSample/example_1.dart b/dartdoc_test/test/testdata/code_sample/example_1.dart similarity index 100% rename from dartdoc_test/test/testdata/codeSample/example_1.dart rename to dartdoc_test/test/testdata/code_sample/example_1.dart diff --git a/dartdoc_test/test/testdata/codeSample/example_2.dart b/dartdoc_test/test/testdata/code_sample/example_2.dart similarity index 100% rename from dartdoc_test/test/testdata/codeSample/example_2.dart rename to dartdoc_test/test/testdata/code_sample/example_2.dart diff --git a/dartdoc_test/test/testdata/codeSample/example_3.dart b/dartdoc_test/test/testdata/code_sample/example_3.dart similarity index 100% rename from dartdoc_test/test/testdata/codeSample/example_3.dart rename to dartdoc_test/test/testdata/code_sample/example_3.dart diff --git a/dartdoc_test/test/testdata/codeSample/example_5.dart b/dartdoc_test/test/testdata/code_sample/example_5.dart similarity index 100% rename from dartdoc_test/test/testdata/codeSample/example_5.dart rename to dartdoc_test/test/testdata/code_sample/example_5.dart diff --git a/dartdoc_test/test/testdata/codeSample/example_6.dart b/dartdoc_test/test/testdata/code_sample/example_6.dart similarity index 100% rename from dartdoc_test/test/testdata/codeSample/example_6.dart rename to dartdoc_test/test/testdata/code_sample/example_6.dart From 683d7fe9bf79ad95bd4b2bbcc554ab539a207577 Mon Sep 17 00:00:00 2001 From: takumma Date: Sun, 18 Aug 2024 06:50:21 +0900 Subject: [PATCH 12/23] add doc comments --- dartdoc_test/analysis_options.yaml | 3 ++ dartdoc_test/lib/dartdoc_test.dart | 2 + dartdoc_test/lib/src/command/add.dart | 16 ++++--- dartdoc_test/lib/src/command/analyze.dart | 6 ++- .../lib/src/command/command_runner.dart | 1 + dartdoc_test/lib/src/extractor.dart | 5 +++ dartdoc_test/lib/src/logger.dart | 38 ++++++++++++---- dartdoc_test/lib/src/reporter.dart | 44 ++++++++++++++++--- dartdoc_test/lib/src/resource.dart | 19 +++++--- dartdoc_test/test/testdata/dartdoc_test.txt | 8 ++-- 10 files changed, 111 insertions(+), 31 deletions(-) diff --git a/dartdoc_test/analysis_options.yaml b/dartdoc_test/analysis_options.yaml index 3376a2c9..a5e5cc76 100644 --- a/dartdoc_test/analysis_options.yaml +++ b/dartdoc_test/analysis_options.yaml @@ -1,3 +1,6 @@ include: package:lints/recommended.yaml +linter: + rules: + - public_member_api_docs analyzer: exclude: [test/testdata/**] diff --git a/dartdoc_test/lib/dartdoc_test.dart b/dartdoc_test/lib/dartdoc_test.dart index 8b98e1b1..4393cbb7 100644 --- a/dartdoc_test/lib/dartdoc_test.dart +++ b/dartdoc_test/lib/dartdoc_test.dart @@ -18,6 +18,8 @@ import 'src/dartdoc_test.dart' show DartdocTest, DartdocTestOptions; import 'src/logger.dart'; import 'src/reporter.dart'; +export 'src/reporter.dart' show Reporter; + /// Test code samples in documentation comments in this package. /// /// this function creates test cases that analyze code samples in documentation diff --git a/dartdoc_test/lib/src/command/add.dart b/dartdoc_test/lib/src/command/add.dart index 9931946d..bfa82f46 100644 --- a/dartdoc_test/lib/src/command/add.dart +++ b/dartdoc_test/lib/src/command/add.dart @@ -16,9 +16,12 @@ import 'dart:io'; import 'package:path/path.dart' as p; -import '../resource.dart'; import 'command_runner.dart'; +/// Handles the `add` command. +/// +/// This command creates a test file for dartdoc_test in `test/dartdoc_test.dart` +/// with a default template. class AddCommand extends DartdocTestCommand { @override String get name => 'add'; @@ -39,7 +42,9 @@ class AddCommand extends DartdocTestCommand { Future run() async { logger.info('Creating "test/dartdoc_test.dart" ...'); - final path = p.join(currentDir.path, 'test', 'dartdoc_test.dart'); + final testDirectory = Directory(p.join(Directory.current.path, 'test')); + + final path = p.join(testDirectory.path, 'dartdoc_test.dart'); final force = argResults.flag('force'); if (!force && File(path).existsSync()) { logger.info('"test/dartdoc_test.dart" is already exists.'); @@ -61,12 +66,11 @@ void main() => runDartdocTest(); '''; // if not exists, create test directory - final directory = Directory(p.join(currentDir.path, 'test')); - if (!directory.existsSync()) { - directory.createSync(); + if (!testDirectory.existsSync()) { + testDirectory.createSync(); } - final file = File(p.join(directory.path, 'dartdoc_test.dart')); + final file = File(p.join(testDirectory.path, 'dartdoc_test.dart')); await file.writeAsString(content); logger.info('Done! You can run "dart test" to analyze code samples.'); } diff --git a/dartdoc_test/lib/src/command/analyze.dart b/dartdoc_test/lib/src/command/analyze.dart index 40dc86c2..59e29357 100644 --- a/dartdoc_test/lib/src/command/analyze.dart +++ b/dartdoc_test/lib/src/command/analyze.dart @@ -18,13 +18,17 @@ import '../dartdoc_test.dart'; import '../logger.dart'; import 'command_runner.dart'; +/// Handles the `analyze` command. +/// +/// This command extracts code samples from documentation comments and analyzes +/// them for errors. class AnalyzeCommand extends DartdocTestCommand { @override String get name => 'analyze'; @override String get description => - 'Analyze code samples in documentation comments in this project.'; + 'Analyze code samples in documentation comments in this package.'; AnalyzeCommand() { argParser diff --git a/dartdoc_test/lib/src/command/command_runner.dart b/dartdoc_test/lib/src/command/command_runner.dart index 88baea45..a07ef293 100644 --- a/dartdoc_test/lib/src/command/command_runner.dart +++ b/dartdoc_test/lib/src/command/command_runner.dart @@ -67,6 +67,7 @@ final class DartdocTestCommandRunner extends CommandRunner { } } +/// The base class for dartdoc_test commands. abstract class DartdocTestCommand extends Command { Logger get logger => (runner as DartdocTestCommandRunner).logger; Reporter get reporter => (runner as DartdocTestCommandRunner).reporter; diff --git a/dartdoc_test/lib/src/extractor.dart b/dartdoc_test/lib/src/extractor.dart index 03fc840a..3024af25 100644 --- a/dartdoc_test/lib/src/extractor.dart +++ b/dartdoc_test/lib/src/extractor.dart @@ -24,6 +24,7 @@ import 'model.dart'; final _md = Document(extensionSet: ExtensionSet.gitHubWeb); +/// Eztract code samples from [ParsedUnitResult]. List extractFile( ParsedUnitResult result, ) { @@ -36,6 +37,7 @@ List extractFile( return samples; } +/// Extract code samples from a file (analysis result) List extractDocumentationComments(ParsedUnitResult r) { final file = SourceFile.fromString(r.content, url: r.uri); @@ -113,6 +115,7 @@ String stripComments(String comment) { return buf.toString().trim(); } +/// Extracts code samples from a documentation comment. List extractCodeSamples( DocumentationComment comment, ) { @@ -158,6 +161,7 @@ List getCodeSamples(String comment) { return codes; } +/// Get imports used on a file. List getImports(SourceFile f, ParsedUnitResult r) { final imports = []; r.unit.accept(_ForEachImportAstVisitor((node) { @@ -226,6 +230,7 @@ class _ForEachText extends NodeVisitor { } extension on DartdocTestFile { + /// get file infomations from [ParsedUnitResult].s static DartdocTestFile from(ParsedUnitResult result) { final sourceFile = SourceFile.fromString(result.content, url: result.uri); final comments = extractDocumentationComments(result); diff --git a/dartdoc_test/lib/src/logger.dart b/dartdoc_test/lib/src/logger.dart index fd0f5c0a..f22b7520 100644 --- a/dartdoc_test/lib/src/logger.dart +++ b/dartdoc_test/lib/src/logger.dart @@ -16,6 +16,7 @@ import 'dart:io' as io; import 'analyzer.dart'; +/// Whether the environment in which it is executed supports ANSI. final supportsAnsi = io.stdout.hasTerminal && io.stdout.supportsAnsiEscapes; // ANSI color codes @@ -25,40 +26,61 @@ final _green = supportsAnsi ? '\u001b[32m' : ''; final _yellow = supportsAnsi ? '\u001b[33m' : ''; final _bold = supportsAnsi ? '\u001b[1m' : ''; +/// enum LogLevel { - debug(0), - info(1), - warning(2), - error(3); - - const LogLevel(this.value); - - final int value; + debug, + info, + warning, + error; + /// bool operator >=(LogLevel other) => index >= other.index; } +/// type of logger callback. typedef LogFunction = void Function(String message, LogLevel level); +/// final class Logger { final LogFunction _log; + + /// Create a new [Logger] with [LogFunction] Logger(this._log); + /// Log a message with [LogLevel.info] void info(String message) => _log(message, LogLevel.info); + + /// Log a message with [LogLevel.debug] void debug(String message) => _log(message, LogLevel.debug); + + /// Log a message with [LogLevel.warning] void warning(String message) => _log(message, LogLevel.warning); + + /// Log a message with [LogLevel.error] void error(String message) => _log(message, LogLevel.error); + + /// Log a message with any [LogLevel] void log(String message, LogLevel level) => _log(message, level); } +/// Summary for code samples analysis results. class Summary { + /// Whether the analysis results contain errors final bool isFailed; + + /// Count of analysis errors caused by code samples (error location in main function) final int errors; + + /// Total count of code samples in analyzed directory. final int samples; + + /// Count of dart files in anaalyzed directory. final int files; + /// Constructor const Summary(this.isFailed, this.errors, this.samples, this.files); + /// Get summery from [DartdocAnalysisResult]. factory Summary.from(List results) { final isFailed = results.indexWhere((r) => r.errors.isNotEmpty) != -1; final errors = diff --git a/dartdoc_test/lib/src/reporter.dart b/dartdoc_test/lib/src/reporter.dart index dc0de5a7..8e965394 100644 --- a/dartdoc_test/lib/src/reporter.dart +++ b/dartdoc_test/lib/src/reporter.dart @@ -14,39 +14,61 @@ import 'dart:io' as io; -import 'package:dartdoc_test/src/resource.dart'; import 'package:path/path.dart' as p; import 'package:dartdoc_test/src/logger.dart'; import 'package:source_span/source_span.dart'; import 'package:test/test.dart'; +/// Reporter for dartdoc_test result. +/// +/// This class provides a way to report issues found in code samples. It can be +/// used to output issues to stdout or to create test cases. If [verbose] flag is +/// `true`, all issues will be reported. Otherwise, only issues caused by the +/// code samples will be reported. +/// +/// If you want to create a custom reporter, you can extend this class and +/// override the [reportSourceFile] method or create custom methods. abstract base class Reporter { + /// Create a new reporter. Reporter({required bool verbose}) : _verbose = verbose; + final _issues = []; - final bool _verbose; - get reportedIssues => _issues; + final bool _verbose; + /// Report issues in a source file. void reportSourceFile(String filename, [void Function(SourceFileReporter)? fn]); + /// Add a new issue. void addIssue(Issue issue) => _issues.add(issue); + /// Create a new reporter for stdout. static Reporter stdout({required bool verbose}) => _ReporterForStdout(verbose: verbose); + + /// Create a new reporter for test. static Reporter test({required bool verbose}) => _RepoterForTest(verbose: verbose); } +/// Reporter for source file. abstract class SourceFileReporter { + /// Report issues in a code sample. + /// you can add custom void reportCodeSample(Uri generatedUrl, [void Function(CodeSampleReporter)? fn]); } +/// Reporter for code sample. abstract class CodeSampleReporter { + /// Report issues void reportIssues(Iterable issues); } +/// Reporter by using stdout. +/// +/// This reporter outputs issues as text by using [io.stdout]. final class _ReporterForStdout extends Reporter implements SourceFileReporter, CodeSampleReporter { final Logger logger; @@ -98,6 +120,10 @@ final class _ReporterForStdout extends Reporter } } +/// Reporter for test. +/// +/// This reporter outputs issues as test cases by using [test] and [group] from +/// `package:test`. final class _RepoterForTest extends Reporter implements SourceFileReporter, CodeSampleReporter { _RepoterForTest({required super.verbose}); @@ -105,7 +131,7 @@ final class _RepoterForTest extends Reporter @override void reportSourceFile(String filename, [void Function(SourceFileReporter)? fn]) { - final path = p.relative(filename, from: currentDir.path); + final path = p.relative(filename, from: io.Directory.current.path); group('[dartdoc_test] $path', () { fn?.call(this); final issues = _issues.where((issue) => issue.path == filename); @@ -116,7 +142,7 @@ final class _RepoterForTest extends Reporter @override void reportCodeSample(Uri generatedUrl, [void Function(CodeSampleReporter)? fn]) { - final path = p.relative(generatedUrl.path, from: currentDir.path); + final path = p.relative(generatedUrl.path, from: io.Directory.current.path); group('[dartdoc_test] $path', () { fn?.call(this); final issues = _issues @@ -146,10 +172,18 @@ final class _RepoterForTest extends Reporter } } +/// Issue found in code samples. class Issue { + /// Path to the file containing a code sample that caused the issue. final String path; + + /// Source span of the comment containing code sample from the original file. final FileSpan? commentSpan; + + /// Source span of the generated code sample file. final FileSpan? generatedSpan; + + /// Message of the issue. final String message; Issue({ diff --git a/dartdoc_test/lib/src/resource.dart b/dartdoc_test/lib/src/resource.dart index eaf92933..fc6f20cb 100644 --- a/dartdoc_test/lib/src/resource.dart +++ b/dartdoc_test/lib/src/resource.dart @@ -26,20 +26,24 @@ import 'model.dart'; const _testPath = '.dartdoc_test'; -final currentDir = Directory.current; +final _currentDir = Directory.current; -/// Context for running tests. manage [resourceProvider]. +/// Context for running dartdoc_test +/// +/// It manages [OverlayResourceProvider] and [context] to provide a way to +/// generate code samples and analyze the code. and also have [codeSampleFiles] +/// that contains all generated code samples file. class DartdocTestContext { DartdocTestContext(this.options) { _resourceProvider = OverlayResourceProvider( PhysicalResourceProvider.INSTANCE, ); _contextCollection = AnalysisContextCollection( - includedPaths: [currentDir.path], + includedPaths: [_currentDir.path], resourceProvider: _resourceProvider, ); - _testDir = Directory(p.join(currentDir.path, options.out ?? _testPath)); + _testDir = Directory(p.join(_currentDir.path, options.out ?? _testPath)); if (options.write) { if (_testDir.existsSync()) { @@ -48,7 +52,7 @@ class DartdocTestContext { _testDir.createSync(); } - _context = _contextCollection.contextFor(currentDir.path); + _context = _contextCollection.contextFor(_currentDir.path); } final DartdocTestOptions options; @@ -62,9 +66,10 @@ class DartdocTestContext { final _files = {}; + AnalysisContext get context => _context; + Set get codeSampleFiles => _files.where((f) => !f.sample.ignore).toSet(); - AnalysisContext get context => _context; void _writeFile(String path, DocumentationCodeSample sample) { final content = sample.wrappedCode(_testDir); @@ -108,7 +113,7 @@ class DartdocTestContext { } List getFiles() { - final files = currentDir + final files = _currentDir .listSync(recursive: true) .whereType() .where((f) => f.path.endsWith('.dart')) diff --git a/dartdoc_test/test/testdata/dartdoc_test.txt b/dartdoc_test/test/testdata/dartdoc_test.txt index fe4dce31..aebda123 100644 --- a/dartdoc_test/test/testdata/dartdoc_test.txt +++ b/dartdoc_test/test/testdata/dartdoc_test.txt @@ -9,7 +9,7 @@ Analyzing code samples ... │ ^ ╵ package:matcher fail - package:dartdoc_test/src/reporter.dart 141:13 _RepoterForTest._reportIssue. + package:dartdoc_test/src/reporter.dart 162:13 _RepoterForTest._reportIssue. 00:00 +0 -1: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for isPalindrome 00:00 +0 -2: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for isPalindrome [E] @@ -19,7 +19,7 @@ Analyzing code samples ... │ ^^^^^^^^^^^^ ╵ package:matcher fail - package:dartdoc_test/src/reporter.dart 141:13 _RepoterForTest._reportIssue. + package:dartdoc_test/src/reporter.dart 162:13 _RepoterForTest._reportIssue. 00:00 +0 -2: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for gcd 00:00 +0 -3: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for gcd [E] @@ -29,7 +29,7 @@ Analyzing code samples ... │ ^^^ ╵ package:matcher fail - package:dartdoc_test/src/reporter.dart 141:13 _RepoterForTest._reportIssue. + package:dartdoc_test/src/reporter.dart 162:13 _RepoterForTest._reportIssue. 00:00 +0 -3: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for length 00:00 +0 -4: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for length [E] @@ -39,7 +39,7 @@ Analyzing code samples ... │ ^^^^^^ ╵ package:matcher fail - package:dartdoc_test/src/reporter.dart 141:13 _RepoterForTest._reportIssue. + package:dartdoc_test/src/reporter.dart 162:13 _RepoterForTest._reportIssue. 00:00 +0 -4: Some tests failed. From 47a2310cf96db5d42ad916d6bfa1c2b82e85d2de Mon Sep 17 00:00:00 2001 From: takumma Date: Mon, 19 Aug 2024 12:06:49 +0900 Subject: [PATCH 13/23] update ignoring to use code block tagging (dart#no-test) --- dartdoc_test/example/lib/example.dart | 6 ++-- dartdoc_test/lib/src/dartdoc_test.dart | 12 -------- dartdoc_test/lib/src/extractor.dart | 28 ++++++----------- dartdoc_test/lib/src/model.dart | 6 +++- dartdoc_test/lib/src/resource.dart | 4 +-- dartdoc_test/test/extractor_test.dart | 34 +++++++++++++++------ dartdoc_test/test/testdata/dartdoc_test.txt | 8 ++--- dartdoc_test/test/testdata/show help.txt | 2 +- 8 files changed, 48 insertions(+), 52 deletions(-) diff --git a/dartdoc_test/example/lib/example.dart b/dartdoc_test/example/lib/example.dart index a80c1888..a85c16b9 100644 --- a/dartdoc_test/example/lib/example.dart +++ b/dartdoc_test/example/lib/example.dart @@ -62,11 +62,9 @@ int multiply(int x, int y) { /// ``` void ignore() {} -/// You can ignore code sample by using `dartdoc_test:ignore_error` tag. -/// -/// ```dart -/// // dartdoc_test:ignore_error +/// You can ignore a code sample by using `no-test` tag. /// +/// ```dart#no-test /// tagIgnore() // it is not reported. /// ``` void tagIgnore() {} diff --git a/dartdoc_test/lib/src/dartdoc_test.dart b/dartdoc_test/lib/src/dartdoc_test.dart index e2b062d0..c36e7649 100644 --- a/dartdoc_test/lib/src/dartdoc_test.dart +++ b/dartdoc_test/lib/src/dartdoc_test.dart @@ -70,16 +70,4 @@ class DartdocTestOptions { List exclude = const [], this.out, }) : exclude = exclude.map((e) => Glob(e)).toList(); - - factory DartdocTestOptions.fromArg([ArgResults? args]) { - if (args == null || args.arguments.isEmpty) { - return DartdocTestOptions(); - } - return DartdocTestOptions( - write: args.flag('write'), - verbose: args.flag('verbose'), - out: args.option('output'), - exclude: args.multiOption('exclude'), - ); - } } diff --git a/dartdoc_test/lib/src/extractor.dart b/dartdoc_test/lib/src/extractor.dart index 3024af25..89396eb2 100644 --- a/dartdoc_test/lib/src/extractor.dart +++ b/dartdoc_test/lib/src/extractor.dart @@ -115,25 +115,12 @@ String stripComments(String comment) { return buf.toString().trim(); } -/// Extracts code samples from a documentation comment. -List extractCodeSamples( - DocumentationComment comment, -) { - final samples = []; - - final codes = getCodeSamples(comment.contents); - for (final code in codes) { - samples.add(DocumentationCodeSample(comment: comment, code: code)); - } - return samples; -} - /// Extracts code samples from a documentation comment. /// one comment can have multiple code samples. /// so this function returns a list of code samples. -List getCodeSamples(String comment) { - final nodes = _md.parse(comment); - var codes = []; +List extractCodeSamples(DocumentationComment comment) { + final nodes = _md.parse(comment.contents); + var samples = []; nodes.accept(_ForEachElement((element) { if (element.tag == 'pre') { if (element.children == null || @@ -147,18 +134,23 @@ List getCodeSamples(String comment) { // when no class is specified, it's considered as dart code block. if (child.tag == 'code' && (child.attributes['class'] == 'language-dart' || + child.attributes['class'] == 'language-dart#no-test' || child.attributes['class'] == null)) { var code = ''; element.children?.accept(_ForEachText((text) { code += text.textContent; })); if (code.isNotEmpty) { - codes.add(code); + samples.add(DocumentationCodeSample( + comment: comment, + code: code, + noTest: child.attributes['class'] == 'language-dart#no-test', + )); } } } })); - return codes; + return samples; } /// Get imports used on a file. diff --git a/dartdoc_test/lib/src/model.dart b/dartdoc_test/lib/src/model.dart index 0cc1cd4b..fd31c0e6 100644 --- a/dartdoc_test/lib/src/model.dart +++ b/dartdoc_test/lib/src/model.dart @@ -67,12 +67,16 @@ class DocumentationCodeSample { /// content of the code sample. final String code; + /// Whether the code sample has a `no-test` tag. + final bool noTest; + DocumentationCodeSample({ required this.comment, required this.code, + required this.noTest, }); - bool get ignore => code.contains('// dartdoc_test:ignore_error'); + /// Whether the code sample has a `main` function. bool get hasMain => code.contains('void main()'); /// Create a sample by wrapping the code with a main function and imports. diff --git a/dartdoc_test/lib/src/resource.dart b/dartdoc_test/lib/src/resource.dart index fc6f20cb..9400b13d 100644 --- a/dartdoc_test/lib/src/resource.dart +++ b/dartdoc_test/lib/src/resource.dart @@ -69,7 +69,7 @@ class DartdocTestContext { AnalysisContext get context => _context; Set get codeSampleFiles => - _files.where((f) => !f.sample.ignore).toSet(); + _files.where((f) => !f.sample.noTest).toSet(); void _writeFile(String path, DocumentationCodeSample sample) { final content = sample.wrappedCode(_testDir); @@ -97,7 +97,7 @@ class DartdocTestContext { List samples, ) { for (final (i, s) in samples.indexed) { - if (s.ignore) { + if (s.noTest) { continue; } diff --git a/dartdoc_test/test/extractor_test.dart b/dartdoc_test/test/extractor_test.dart index aae9e38b..8d6aa4b2 100644 --- a/dartdoc_test/test/extractor_test.dart +++ b/dartdoc_test/test/extractor_test.dart @@ -13,6 +13,8 @@ // limitations under the License. import 'package:dartdoc_test/src/extractor.dart'; +import 'package:dartdoc_test/src/model.dart'; +import 'package:source_span/source_span.dart'; import 'package:test/test.dart'; void main() { @@ -72,24 +74,36 @@ void main() { }); }); - group('getCodeSamples', () { + group('extractCodeSamples', () { test('can extract code samples', () { - final comment = 'example:\n```dart\nfinal x = 1;\n```'; - final result = getCodeSamples(comment); + final contents = 'example:\n```dart\nfinal x = 1;\n```'; + final comment = DocumentationComment( + path: 'test.dart', + contents: contents, + span: SourceFile.fromString(contents, url: Uri.parse('test.dart')) + .span(0, contents.length), + imports: [], + ); + final result = extractCodeSamples(comment); expect( - result, - ['final x = 1;\n'], + result.first.code, + 'final x = 1;\n', ); }); test('can extract multiple code samples', () { - final comment = + final contents = 'example:\n```dart\nfinal x = 1;\n```\n```dart\nfinal y = 2;\n```'; - final result = getCodeSamples(comment); - expect( - result, - ['final x = 1;\n', 'final y = 2;\n'], + final comment = DocumentationComment( + path: 'test.dart', + contents: contents, + span: SourceFile.fromString(contents, url: Uri.parse('test.dart')) + .span(0, contents.length), + imports: [], ); + final result = extractCodeSamples(comment); + expect(result[0].code, 'final x = 1;\n'); + expect(result[1].code, 'final y = 2;\n'); }); }); } diff --git a/dartdoc_test/test/testdata/dartdoc_test.txt b/dartdoc_test/test/testdata/dartdoc_test.txt index aebda123..0d0f268b 100644 --- a/dartdoc_test/test/testdata/dartdoc_test.txt +++ b/dartdoc_test/test/testdata/dartdoc_test.txt @@ -9,7 +9,7 @@ Analyzing code samples ... │ ^ ╵ package:matcher fail - package:dartdoc_test/src/reporter.dart 162:13 _RepoterForTest._reportIssue. + package:dartdoc_test/src/reporter.dart 167:13 _RepoterForTest._reportIssue. 00:00 +0 -1: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for isPalindrome 00:00 +0 -2: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for isPalindrome [E] @@ -19,7 +19,7 @@ Analyzing code samples ... │ ^^^^^^^^^^^^ ╵ package:matcher fail - package:dartdoc_test/src/reporter.dart 162:13 _RepoterForTest._reportIssue. + package:dartdoc_test/src/reporter.dart 167:13 _RepoterForTest._reportIssue. 00:00 +0 -2: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for gcd 00:00 +0 -3: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for gcd [E] @@ -29,7 +29,7 @@ Analyzing code samples ... │ ^^^ ╵ package:matcher fail - package:dartdoc_test/src/reporter.dart 162:13 _RepoterForTest._reportIssue. + package:dartdoc_test/src/reporter.dart 167:13 _RepoterForTest._reportIssue. 00:00 +0 -3: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for length 00:00 +0 -4: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for length [E] @@ -39,7 +39,7 @@ Analyzing code samples ... │ ^^^^^^ ╵ package:matcher fail - package:dartdoc_test/src/reporter.dart 162:13 _RepoterForTest._reportIssue. + package:dartdoc_test/src/reporter.dart 167:13 _RepoterForTest._reportIssue. 00:00 +0 -4: Some tests failed. diff --git a/dartdoc_test/test/testdata/show help.txt b/dartdoc_test/test/testdata/show help.txt index c76c0e73..d3244892 100644 --- a/dartdoc_test/test/testdata/show help.txt +++ b/dartdoc_test/test/testdata/show help.txt @@ -9,6 +9,6 @@ Global options: Available commands: add Add dartdoc_test test file to "test/dartdoc_test.dart" - analyze Analyze code samples in documentation comments in this project. + analyze Analyze code samples in documentation comments in this package. Run "dartdoc_test help " for more information about a command. \ No newline at end of file From d8491df38be3c74e0690904f8e04a357574a2477 Mon Sep 17 00:00:00 2001 From: takumma Date: Mon, 19 Aug 2024 19:43:59 +0900 Subject: [PATCH 14/23] add public member documentations --- dartdoc_test/lib/src/analyzer.dart | 16 +++++++++- dartdoc_test/lib/src/command/add.dart | 1 + dartdoc_test/lib/src/command/analyze.dart | 1 + .../lib/src/command/command_runner.dart | 7 +++++ dartdoc_test/lib/src/dartdoc_test.dart | 16 ++++++++-- dartdoc_test/lib/src/extractor.dart | 2 +- dartdoc_test/lib/src/logger.dart | 13 +++++++-- dartdoc_test/lib/src/model.dart | 29 +++++++++++++++---- dartdoc_test/lib/src/reporter.dart | 1 + dartdoc_test/lib/src/resource.dart | 12 ++++++++ 10 files changed, 86 insertions(+), 12 deletions(-) diff --git a/dartdoc_test/lib/src/analyzer.dart b/dartdoc_test/lib/src/analyzer.dart index 651ef634..a0977131 100644 --- a/dartdoc_test/lib/src/analyzer.dart +++ b/dartdoc_test/lib/src/analyzer.dart @@ -19,6 +19,7 @@ import 'package:source_span/source_span.dart'; import 'model.dart'; +/// Get analysis result for a code sample file. Future getAnalysisResult( AnalysisContext context, CodeSampleFile file, @@ -45,7 +46,7 @@ Future getAnalysisResult( return DartdocAnalysisResult(file, []); } -// get original file span from sample file span +/// get original file span from sample file span. FileSpan? getOriginalSubSpan({ required FileSpan sample, required FileSpan original, @@ -57,11 +58,18 @@ FileSpan? getOriginalSubSpan({ return original.subspan(offset, offset + sample.length); } +/// Dartdoc error result class DartdocErrorResult { + /// Error description final AnalysisError error; + + /// Source span of the comment containing code sample from the original file. final FileSpan? commentSpan; + + /// Source span of the generated code sample file. final FileSpan? generatedSpan; + /// Create a new instance of [DartdocErrorResult] DartdocErrorResult({ required this.error, required this.commentSpan, @@ -69,11 +77,17 @@ class DartdocErrorResult { }); } +/// Dartdoc analysis result class DartdocAnalysisResult { + /// generated code sample file final CodeSampleFile file; + + /// list of analysis errors final List errors; + /// Wheather the analysis result has error bool get hasError => errors.any((e) => e.commentSpan != null); + /// Create a new instance of [DartdocAnalysisResult] DartdocAnalysisResult(this.file, this.errors); } diff --git a/dartdoc_test/lib/src/command/add.dart b/dartdoc_test/lib/src/command/add.dart index bfa82f46..2f809799 100644 --- a/dartdoc_test/lib/src/command/add.dart +++ b/dartdoc_test/lib/src/command/add.dart @@ -30,6 +30,7 @@ class AddCommand extends DartdocTestCommand { String get description => 'Add dartdoc_test test file to "test/dartdoc_test.dart"'; + /// Create a new [AddCommand]. AddCommand() { argParser.addFlag( 'force', diff --git a/dartdoc_test/lib/src/command/analyze.dart b/dartdoc_test/lib/src/command/analyze.dart index 59e29357..1d5c05ed 100644 --- a/dartdoc_test/lib/src/command/analyze.dart +++ b/dartdoc_test/lib/src/command/analyze.dart @@ -30,6 +30,7 @@ class AnalyzeCommand extends DartdocTestCommand { String get description => 'Analyze code samples in documentation comments in this package.'; + /// Create a new [AnalyzeCommand]. AnalyzeCommand() { argParser ..addFlag( diff --git a/dartdoc_test/lib/src/command/command_runner.dart b/dartdoc_test/lib/src/command/command_runner.dart index a07ef293..fb4beb00 100644 --- a/dartdoc_test/lib/src/command/command_runner.dart +++ b/dartdoc_test/lib/src/command/command_runner.dart @@ -22,7 +22,9 @@ import '../reporter.dart'; import 'add.dart'; import 'analyze.dart'; +/// The command runner for dartdoc_test. final class DartdocTestCommandRunner extends CommandRunner { + /// Create a new command runner. DartdocTestCommandRunner() : super( 'dartdoc_test', @@ -38,8 +40,10 @@ final class DartdocTestCommandRunner extends CommandRunner { addCommand(AddCommand()); } + /// The logger for the command runner. late final Logger logger; + /// The reporter for the command runner. late final Reporter reporter; @override @@ -69,7 +73,10 @@ final class DartdocTestCommandRunner extends CommandRunner { /// The base class for dartdoc_test commands. abstract class DartdocTestCommand extends Command { + /// The logger to log messages. Logger get logger => (runner as DartdocTestCommandRunner).logger; + + /// The reporter to report issues. Reporter get reporter => (runner as DartdocTestCommandRunner).reporter; @override diff --git a/dartdoc_test/lib/src/dartdoc_test.dart b/dartdoc_test/lib/src/dartdoc_test.dart index c36e7649..4376ef27 100644 --- a/dartdoc_test/lib/src/dartdoc_test.dart +++ b/dartdoc_test/lib/src/dartdoc_test.dart @@ -14,8 +14,6 @@ import 'dart:io'; -import 'package:args/args.dart'; - import 'package:analyzer/dart/analysis/results.dart'; import 'package:glob/glob.dart'; @@ -23,9 +21,12 @@ import 'analyzer.dart'; import 'extractor.dart'; import 'resource.dart'; +/// Dartdoc test class DartdocTest { + /// Create a new [DartdocTest] with [options]. DartdocTest(this.options) : _testContext = DartdocTestContext(options); + /// The options for running dartdoc_test. final DartdocTestOptions options; final DartdocTestContext _testContext; @@ -55,15 +56,26 @@ class DartdocTest { return results; } + /// Get all dart files in the current directory. List getFiles() => _testContext.getFiles(); } +/// Options for running dartdoc_test class DartdocTestOptions { + /// Whether to write generated code samples to physical files. final bool write; + + /// Whether to output verbose information. final bool verbose; + + /// The glob patterns to exclude files from analysis. final List exclude; + + /// The output directory for generated code samples (optional). + /// if it is `null`, the default output directory is `./.dartdoc_test`. final String? out; + /// Create a new [DartdocTestOptions]. DartdocTestOptions({ this.write = false, this.verbose = false, diff --git a/dartdoc_test/lib/src/extractor.dart b/dartdoc_test/lib/src/extractor.dart index 89396eb2..f09aa48a 100644 --- a/dartdoc_test/lib/src/extractor.dart +++ b/dartdoc_test/lib/src/extractor.dart @@ -222,7 +222,7 @@ class _ForEachText extends NodeVisitor { } extension on DartdocTestFile { - /// get file infomations from [ParsedUnitResult].s + /// get file infomations from [ParsedUnitResult]. static DartdocTestFile from(ParsedUnitResult result) { final sourceFile = SourceFile.fromString(result.content, url: result.uri); final comments = extractDocumentationComments(result); diff --git a/dartdoc_test/lib/src/logger.dart b/dartdoc_test/lib/src/logger.dart index f22b7520..39034149 100644 --- a/dartdoc_test/lib/src/logger.dart +++ b/dartdoc_test/lib/src/logger.dart @@ -26,21 +26,30 @@ final _green = supportsAnsi ? '\u001b[32m' : ''; final _yellow = supportsAnsi ? '\u001b[33m' : ''; final _bold = supportsAnsi ? '\u001b[1m' : ''; -/// +/// A enum type for defining logging levels. enum LogLevel { + /// debug information. debug, + + /// standard information. info, + + /// warning. warning, + + /// error. error; - /// bool operator >=(LogLevel other) => index >= other.index; } /// type of logger callback. typedef LogFunction = void Function(String message, LogLevel level); +/// A simple logger class that logs messages with different levels. /// +/// you can set a custom log function by passing a [LogFunction] to the +/// constructor and use the [LogLevel] to log messages with different levels. final class Logger { final LogFunction _log; diff --git a/dartdoc_test/lib/src/model.dart b/dartdoc_test/lib/src/model.dart index fd31c0e6..42b6aef8 100644 --- a/dartdoc_test/lib/src/model.dart +++ b/dartdoc_test/lib/src/model.dart @@ -18,36 +18,45 @@ import 'dart:io'; import 'package:path/path.dart' as p; import 'package:source_span/source_span.dart'; +/// A dart file that contains documentation comments and code samples. class DartdocTestFile { + /// Create a new [DartdocTestFile]. DartdocTestFile(this._sourceFile, this._imports, this._comments); final SourceFile _sourceFile; final List _imports; final List _comments; + /// The source file. SourceFile get sourceFile => _sourceFile; + + /// The imports used in the source file. List get imports => _imports; + + /// The documentation comments in the source file. List get comments => _comments; } /// A documentation comment extracted from a source file. class DocumentationComment { final String _path; - - /// The span of the comment in the source file. final FileSpan _span; - - /// The contents of the comment. (includes code blocks and text) final String _contents; - - /// The imports used in the source file. final List _imports; + /// The path of the source file that contains the comment. String get path => _path; + + /// The span of the comment in the source file. FileSpan get span => _span; + + /// The contents of the comment. (includes code blocks and text) String get contents => _contents; + + /// The imports used in the source file. List get imports => _imports; + /// Create a new [DocumentationComment]. DocumentationComment({ required String path, required String contents, @@ -70,6 +79,7 @@ class DocumentationCodeSample { /// Whether the code sample has a `no-test` tag. final bool noTest; + /// Create a new [DocumentationCodeSample]. DocumentationCodeSample({ required this.comment, required this.code, @@ -103,11 +113,18 @@ class DocumentationCodeSample { } } +/// A generated code sample file. class CodeSampleFile { + /// The path of the generated file. final String path; + + /// The generated source file. final SourceFile sourceFile; + + /// The code sample that generated the file. final DocumentationCodeSample sample; + /// Create a new [CodeSampleFile]. CodeSampleFile({ required this.path, required this.sourceFile, diff --git a/dartdoc_test/lib/src/reporter.dart b/dartdoc_test/lib/src/reporter.dart index 8e965394..774ca1ed 100644 --- a/dartdoc_test/lib/src/reporter.dart +++ b/dartdoc_test/lib/src/reporter.dart @@ -186,6 +186,7 @@ class Issue { /// Message of the issue. final String message; + /// Create a new issue. Issue({ required this.path, this.commentSpan, diff --git a/dartdoc_test/lib/src/resource.dart b/dartdoc_test/lib/src/resource.dart index 9400b13d..7bec91d4 100644 --- a/dartdoc_test/lib/src/resource.dart +++ b/dartdoc_test/lib/src/resource.dart @@ -34,6 +34,7 @@ final _currentDir = Directory.current; /// generate code samples and analyze the code. and also have [codeSampleFiles] /// that contains all generated code samples file. class DartdocTestContext { + /// Create a [DartdocTestContext] with [options]. DartdocTestContext(this.options) { _resourceProvider = OverlayResourceProvider( PhysicalResourceProvider.INSTANCE, @@ -55,6 +56,7 @@ class DartdocTestContext { _context = _contextCollection.contextFor(_currentDir.path); } + /// Options for running dartdoc_test final DartdocTestOptions options; late final OverlayResourceProvider _resourceProvider; @@ -66,8 +68,10 @@ class DartdocTestContext { final _files = {}; + /// Analysis context for the current directory AnalysisContext get context => _context; + /// The generated code samples files that are not excluded with `no-test` tag. Set get codeSampleFiles => _files.where((f) => !f.sample.noTest).toSet(); @@ -92,6 +96,10 @@ class DartdocTestContext { )); } + /// Write code samples to the file. + /// + /// In default, it will write to the overlay (in-memory) file system. But, + /// if [options.write] is true, it will write to the pyscial file system. void writeCodeSamples( String filePath, List samples, @@ -112,6 +120,10 @@ class DartdocTestContext { return !options.exclude.any((glob) => glob.matches(path)); } + /// Get all dart files in the current directory. + /// + /// If [options.exclude] is provided, it will exclude files that match the + /// patterns. List getFiles() { final files = _currentDir .listSync(recursive: true) From 01c146a1c97cdd8b4e42410f0bc7a3aa90c3dc51 Mon Sep 17 00:00:00 2001 From: takumma Date: Mon, 19 Aug 2024 19:49:38 +0900 Subject: [PATCH 15/23] fix --- dartdoc_test/lib/src/extractor.dart | 1 + dartdoc_test/lib/src/logger.dart | 3 +-- dartdoc_test/test/analyzer_test.dart | 2 -- 3 files changed, 2 insertions(+), 4 deletions(-) diff --git a/dartdoc_test/lib/src/extractor.dart b/dartdoc_test/lib/src/extractor.dart index f09aa48a..a1d6ee15 100644 --- a/dartdoc_test/lib/src/extractor.dart +++ b/dartdoc_test/lib/src/extractor.dart @@ -223,6 +223,7 @@ class _ForEachText extends NodeVisitor { extension on DartdocTestFile { /// get file infomations from [ParsedUnitResult]. + // ignore: unused_element static DartdocTestFile from(ParsedUnitResult result) { final sourceFile = SourceFile.fromString(result.content, url: result.uri); final comments = extractDocumentationComments(result); diff --git a/dartdoc_test/lib/src/logger.dart b/dartdoc_test/lib/src/logger.dart index 39034149..bbb5d830 100644 --- a/dartdoc_test/lib/src/logger.dart +++ b/dartdoc_test/lib/src/logger.dart @@ -23,8 +23,6 @@ final supportsAnsi = io.stdout.hasTerminal && io.stdout.supportsAnsiEscapes; final _reset = supportsAnsi ? '\u001b[0m' : ''; final _red = supportsAnsi ? '\u001b[31m' : ''; final _green = supportsAnsi ? '\u001b[32m' : ''; -final _yellow = supportsAnsi ? '\u001b[33m' : ''; -final _bold = supportsAnsi ? '\u001b[1m' : ''; /// A enum type for defining logging levels. enum LogLevel { @@ -40,6 +38,7 @@ enum LogLevel { /// error. error; + /// operator to compare [LogLevel]s. bool operator >=(LogLevel other) => index >= other.index; } diff --git a/dartdoc_test/test/analyzer_test.dart b/dartdoc_test/test/analyzer_test.dart index 24af5ed8..6f5b065f 100644 --- a/dartdoc_test/test/analyzer_test.dart +++ b/dartdoc_test/test/analyzer_test.dart @@ -50,6 +50,4 @@ void main() { expect(result, isNull); // not found. }); }); - - // TODO: add emoji offset test } From 305fea14e49c9d9da3f9976a61c9e299bb1996e5 Mon Sep 17 00:00:00 2001 From: takumma Date: Tue, 20 Aug 2024 10:28:47 +0900 Subject: [PATCH 16/23] switch default output directory to --- dartdoc_test/.gitignore | 1 - dartdoc_test/README.md | 10 ++++------ dartdoc_test/lib/src/dartdoc_test.dart | 2 +- dartdoc_test/lib/src/resource.dart | 2 +- ...ze command by default with verbose flag.txt | 18 +++++++----------- .../run analyze command with verbose flag.txt | 18 +++++++----------- 6 files changed, 20 insertions(+), 31 deletions(-) delete mode 100644 dartdoc_test/.gitignore diff --git a/dartdoc_test/.gitignore b/dartdoc_test/.gitignore deleted file mode 100644 index 0cb32c44..00000000 --- a/dartdoc_test/.gitignore +++ /dev/null @@ -1 +0,0 @@ -.dartdoc_test \ No newline at end of file diff --git a/dartdoc_test/README.md b/dartdoc_test/README.md index 56c04742..51ecb2fa 100644 --- a/dartdoc_test/README.md +++ b/dartdoc_test/README.md @@ -53,15 +53,13 @@ void main() => runDartdocTest(); # Ignore analysis -If you don't want to analyze a particular code sample, you can exclude it by adding an `// dartdoc_test:ignore_error` comment within the code sample. +If you don't want to analyze a particular code sample, you can exclude it by adding tag `#no-test` within the code block. -```` +````txt /// This code sample will not be analyzed. /// -/// ```dart -/// // dartdoc_test:ignore_error -/// -/// tagIgnore() // it is not reported. +/// ```dart#no-test +/// final a = 1 // it is not reported. /// ``` ```` diff --git a/dartdoc_test/lib/src/dartdoc_test.dart b/dartdoc_test/lib/src/dartdoc_test.dart index 4376ef27..18a69931 100644 --- a/dartdoc_test/lib/src/dartdoc_test.dart +++ b/dartdoc_test/lib/src/dartdoc_test.dart @@ -72,7 +72,7 @@ class DartdocTestOptions { final List exclude; /// The output directory for generated code samples (optional). - /// if it is `null`, the default output directory is `./.dartdoc_test`. + /// if it is `null`, the default output directory is `.dart_tool/dartdoc_test`. final String? out; /// Create a new [DartdocTestOptions]. diff --git a/dartdoc_test/lib/src/resource.dart b/dartdoc_test/lib/src/resource.dart index 7bec91d4..f3034d7a 100644 --- a/dartdoc_test/lib/src/resource.dart +++ b/dartdoc_test/lib/src/resource.dart @@ -24,7 +24,7 @@ import 'package:source_span/source_span.dart'; import 'dartdoc_test.dart'; import 'model.dart'; -const _testPath = '.dartdoc_test'; +const _testPath = '.dart_tool/dartdoc_test'; final _currentDir = Directory.current; diff --git a/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt b/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt index d59452d6..e5979cec 100644 --- a/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt +++ b/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt @@ -1,39 +1,35 @@ $ dart run dartdoc_test -v Extracting code samples ... Analyzing code samples ... -original error: .dartdoc_test/error_example_0.dart:5:27: Expected to find ';'. +original error: .dart_tool/dartdoc_test/error_example_0.dart:5:27: Expected to find ';'. package:example/error_example.dart:17:29: : Expected to find ';'. ╷ 17 │ /// final fact = factorial(5) │ ^ ╵ -original error: .dartdoc_test/error_example_1.dart:5:24: Local variable 'isPalindrome' can't be referenced before it is declared. +original error: .dart_tool/dartdoc_test/error_example_1.dart:5:24: Local variable 'isPalindrome' can't be referenced before it is declared. package:example/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. ╷ 31 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); │ ^^^^^^^^^^^^ ╵ -.dartdoc_test/error_example_1.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) -original error: .dartdoc_test/error_example_2.dart:5:15: Local variable 'gcd' can't be referenced before it is declared. +.dart_tool/dartdoc_test/error_example_1.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) +original error: .dart_tool/dartdoc_test/error_example_2.dart:5:15: Local variable 'gcd' can't be referenced before it is declared. package:example/error_example.dart:39:36: : Local variable 'gcd' can't be referenced before it is declared. ╷ 39 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. │ ^^^ ╵ -.dartdoc_test/error_example_2.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) -original error: .dartdoc_test/error_example_3.dart:5:20: The getter 'length' isn't defined for the type 'int'. +.dart_tool/dartdoc_test/error_example_2.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) +original error: .dart_tool/dartdoc_test/error_example_3.dart:5:20: The getter 'length' isn't defined for the type 'int'. package:example/error_example.dart:53:32: : The getter 'length' isn't defined for the type 'int'. ╷ 53 │ /// Should return: The getter 'length' isn't defined for the class 'int'. │ ^^^^^^ ╵ -.dartdoc_test/error_example_3.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_0.dart:2:7: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_1.dart:2:7: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_2.dart:2:7: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_3.dart:2:7: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dart_tool/dartdoc_test/error_example_3.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) FAILED: 4 issues found (Found 10 code samples in 2 files) \ No newline at end of file diff --git a/dartdoc_test/test/testdata/run analyze command with verbose flag.txt b/dartdoc_test/test/testdata/run analyze command with verbose flag.txt index 56e37011..80ea6407 100644 --- a/dartdoc_test/test/testdata/run analyze command with verbose flag.txt +++ b/dartdoc_test/test/testdata/run analyze command with verbose flag.txt @@ -1,39 +1,35 @@ $ dart run dartdoc_test analyze -v Extracting code samples ... Analyzing code samples ... -original error: .dartdoc_test/error_example_0.dart:5:27: Expected to find ';'. +original error: .dart_tool/dartdoc_test/error_example_0.dart:5:27: Expected to find ';'. package:example/error_example.dart:17:29: : Expected to find ';'. ╷ 17 │ /// final fact = factorial(5) │ ^ ╵ -original error: .dartdoc_test/error_example_1.dart:5:24: Local variable 'isPalindrome' can't be referenced before it is declared. +original error: .dart_tool/dartdoc_test/error_example_1.dart:5:24: Local variable 'isPalindrome' can't be referenced before it is declared. package:example/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. ╷ 31 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); │ ^^^^^^^^^^^^ ╵ -.dartdoc_test/error_example_1.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) -original error: .dartdoc_test/error_example_2.dart:5:15: Local variable 'gcd' can't be referenced before it is declared. +.dart_tool/dartdoc_test/error_example_1.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) +original error: .dart_tool/dartdoc_test/error_example_2.dart:5:15: Local variable 'gcd' can't be referenced before it is declared. package:example/error_example.dart:39:36: : Local variable 'gcd' can't be referenced before it is declared. ╷ 39 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. │ ^^^ ╵ -.dartdoc_test/error_example_2.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) -original error: .dartdoc_test/error_example_3.dart:5:20: The getter 'length' isn't defined for the type 'int'. +.dart_tool/dartdoc_test/error_example_2.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) +original error: .dart_tool/dartdoc_test/error_example_3.dart:5:20: The getter 'length' isn't defined for the type 'int'. package:example/error_example.dart:53:32: : The getter 'length' isn't defined for the type 'int'. ╷ 53 │ /// Should return: The getter 'length' isn't defined for the class 'int'. │ ^^^^^^ ╵ -.dartdoc_test/error_example_3.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_0.dart:2:7: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_1.dart:2:7: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_2.dart:2:7: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) -.dartdoc_test/example_3.dart:2:7: Unused import: 'dart:convert'. (ignored because issue occurs in the generated code) +.dart_tool/dartdoc_test/error_example_3.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) FAILED: 4 issues found (Found 10 code samples in 2 files) \ No newline at end of file From 7af65a3979b2428520f9d0a9ff48634b55ff80c1 Mon Sep 17 00:00:00 2001 From: takumma Date: Tue, 20 Aug 2024 12:07:46 +0900 Subject: [PATCH 17/23] update CHANGELOG --- dartdoc_test/CHANGELOG.md | 1 + dartdoc_test/README.md | 1 - dartdoc_test/lib/src/extractor.dart | 11 ----------- dartdoc_test/lib/src/model.dart | 8 ++++---- dartdoc_test/test/dartdoc_test.dart | 4 +++- dartdoc_test/test/integration_test.dart | 4 ++-- .../run analyze command with exclude option.txt | 4 ++-- 7 files changed, 12 insertions(+), 21 deletions(-) diff --git a/dartdoc_test/CHANGELOG.md b/dartdoc_test/CHANGELOG.md index 44b64a9b..f88c851e 100644 --- a/dartdoc_test/CHANGELOG.md +++ b/dartdoc_test/CHANGELOG.md @@ -1 +1,2 @@ ## v0.1.0 + * Initial release, with code sample extraction, analysis, and some options to write or ignore analysis. diff --git a/dartdoc_test/README.md b/dartdoc_test/README.md index 51ecb2fa..11df4eb8 100644 --- a/dartdoc_test/README.md +++ b/dartdoc_test/README.md @@ -48,7 +48,6 @@ import 'package:dartdoc_test/dartdoc_test.dart'; /// /// If you want to test only specific files, you can use [exclude] options. void main() => runDartdocTest(); - ``` # Ignore analysis diff --git a/dartdoc_test/lib/src/extractor.dart b/dartdoc_test/lib/src/extractor.dart index a1d6ee15..21036fac 100644 --- a/dartdoc_test/lib/src/extractor.dart +++ b/dartdoc_test/lib/src/extractor.dart @@ -220,14 +220,3 @@ class _ForEachText extends NodeVisitor { @override void visitText(Text text) => _forEach(text); } - -extension on DartdocTestFile { - /// get file infomations from [ParsedUnitResult]. - // ignore: unused_element - static DartdocTestFile from(ParsedUnitResult result) { - final sourceFile = SourceFile.fromString(result.content, url: result.uri); - final comments = extractDocumentationComments(result); - final imports = getImports(sourceFile, result); - return DartdocTestFile(sourceFile, imports, comments); - } -} diff --git a/dartdoc_test/lib/src/model.dart b/dartdoc_test/lib/src/model.dart index 42b6aef8..dba5d6a9 100644 --- a/dartdoc_test/lib/src/model.dart +++ b/dartdoc_test/lib/src/model.dart @@ -19,7 +19,7 @@ import 'package:path/path.dart' as p; import 'package:source_span/source_span.dart'; /// A dart file that contains documentation comments and code samples. -class DartdocTestFile { +final class DartdocTestFile { /// Create a new [DartdocTestFile]. DartdocTestFile(this._sourceFile, this._imports, this._comments); @@ -38,7 +38,7 @@ class DartdocTestFile { } /// A documentation comment extracted from a source file. -class DocumentationComment { +final class DocumentationComment { final String _path; final FileSpan _span; final String _contents; @@ -69,7 +69,7 @@ class DocumentationComment { } /// A code sample extracted from a documentation comment. -class DocumentationCodeSample { +final class DocumentationCodeSample { /// The documentation comment that contains the code sample. final DocumentationComment comment; @@ -114,7 +114,7 @@ class DocumentationCodeSample { } /// A generated code sample file. -class CodeSampleFile { +final class CodeSampleFile { /// The path of the generated file. final String path; diff --git a/dartdoc_test/test/dartdoc_test.dart b/dartdoc_test/test/dartdoc_test.dart index f5196794..4d47d354 100644 --- a/dartdoc_test/test/dartdoc_test.dart +++ b/dartdoc_test/test/dartdoc_test.dart @@ -7,4 +7,6 @@ import 'package:dartdoc_test/dartdoc_test.dart'; /// and you can see the problems details. /// /// If you want to test only specific files, you can use [exclude] option. -void main() => runDartdocTest(); +void main() => runDartdocTest( + exclude: ['example/**'], + ); diff --git a/dartdoc_test/test/integration_test.dart b/dartdoc_test/test/integration_test.dart index 2ff9864c..236bcaa6 100644 --- a/dartdoc_test/test/integration_test.dart +++ b/dartdoc_test/test/integration_test.dart @@ -24,8 +24,8 @@ void main() { testWithGolden('run analyze command by default', ['']); testWithGolden('run analyze command by default with verbose flag', ['-v']); testWithGolden('run analyze command with verbose flag', ['analyze', '-v']); - testWithGolden( - 'run analyze command with exclude option', ['analyze', '-x', 'lib/**']); + testWithGolden('run analyze command with exclude option', + ['analyze', '-x', 'lib/error_example.dart']); group('extractor', () { test('extract code samples in example directory', () async { diff --git a/dartdoc_test/test/testdata/run analyze command with exclude option.txt b/dartdoc_test/test/testdata/run analyze command with exclude option.txt index c2318aa9..ca693adb 100644 --- a/dartdoc_test/test/testdata/run analyze command with exclude option.txt +++ b/dartdoc_test/test/testdata/run analyze command with exclude option.txt @@ -1,5 +1,5 @@ -$ dart run dartdoc_test analyze -x lib/** +$ dart run dartdoc_test analyze -x lib/error_example.dart Extracting code samples ... Analyzing code samples ... No issues found. -PASSED: No issues found! (Found 0 code samples in 0 files) \ No newline at end of file +PASSED: No issues found! (Found 6 code samples in 1 files) \ No newline at end of file From 96d090ec5bb7965e7adf852d0c2871d8b98dd7cc Mon Sep 17 00:00:00 2001 From: takumma Date: Tue, 20 Aug 2024 21:51:09 +0900 Subject: [PATCH 18/23] fix to make some class to final --- dartdoc_test/lib/src/model.dart | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/dartdoc_test/lib/src/model.dart b/dartdoc_test/lib/src/model.dart index dba5d6a9..914270b4 100644 --- a/dartdoc_test/lib/src/model.dart +++ b/dartdoc_test/lib/src/model.dart @@ -86,11 +86,8 @@ final class DocumentationCodeSample { required this.noTest, }); - /// Whether the code sample has a `main` function. - bool get hasMain => code.contains('void main()'); - /// Create a sample by wrapping the code with a main function and imports. - String wrappedCode(Directory testDir) { + String wrappedCode(Directory testDir, {bool wrapWithMain = false}) { final fileName = comment.span.sourceUrl; final buf = StringBuffer(); @@ -105,10 +102,10 @@ final class DocumentationCodeSample { } } buf.writeln(); - if (!hasMain) buf.writeln('void main() {'); + if (wrapWithMain) buf.writeln('void main() {'); buf.writeAll(LineSplitter.split(code).map((l) => ' $l'), '\n'); buf.writeln(); - if (!hasMain) buf.writeln('}'); + if (wrapWithMain) buf.writeln('}'); return buf.toString(); } } From 9ccdecd3b6448df99b0be1226d2477b4c78390f2 Mon Sep 17 00:00:00 2001 From: takumma Date: Tue, 20 Aug 2024 22:09:09 +0900 Subject: [PATCH 19/23] remove Reporter constructor, add some comments, and some fixes --- dartdoc_test/lib/src/model.dart | 14 +++++++++++--- dartdoc_test/lib/src/reporter.dart | 10 +++------- dartdoc_test/test/testdata/dartdoc_test.txt | 8 ++++---- 3 files changed, 18 insertions(+), 14 deletions(-) diff --git a/dartdoc_test/lib/src/model.dart b/dartdoc_test/lib/src/model.dart index 914270b4..3848c410 100644 --- a/dartdoc_test/lib/src/model.dart +++ b/dartdoc_test/lib/src/model.dart @@ -77,6 +77,12 @@ final class DocumentationCodeSample { final String code; /// Whether the code sample has a `no-test` tag. + /// + /// ```text + /// /// ```dart no-test + /// /// // This code will not be tested. + /// /// ``` + /// ``` final bool noTest; /// Create a new [DocumentationCodeSample]. @@ -86,8 +92,10 @@ final class DocumentationCodeSample { required this.noTest, }); + bool get hasMain => code.contains('void main()'); + /// Create a sample by wrapping the code with a main function and imports. - String wrappedCode(Directory testDir, {bool wrapWithMain = false}) { + String wrappedCode(Directory testDir) { final fileName = comment.span.sourceUrl; final buf = StringBuffer(); @@ -102,10 +110,10 @@ final class DocumentationCodeSample { } } buf.writeln(); - if (wrapWithMain) buf.writeln('void main() {'); + if (!hasMain) buf.writeln('void main() {'); buf.writeAll(LineSplitter.split(code).map((l) => ' $l'), '\n'); buf.writeln(); - if (wrapWithMain) buf.writeln('}'); + if (!hasMain) buf.writeln('}'); return buf.toString(); } } diff --git a/dartdoc_test/lib/src/reporter.dart b/dartdoc_test/lib/src/reporter.dart index 774ca1ed..3cf05fd0 100644 --- a/dartdoc_test/lib/src/reporter.dart +++ b/dartdoc_test/lib/src/reporter.dart @@ -29,13 +29,8 @@ import 'package:test/test.dart'; /// If you want to create a custom reporter, you can extend this class and /// override the [reportSourceFile] method or create custom methods. abstract base class Reporter { - /// Create a new reporter. - Reporter({required bool verbose}) : _verbose = verbose; - final _issues = []; - final bool _verbose; - /// Report issues in a source file. void reportSourceFile(String filename, [void Function(SourceFileReporter)? fn]); @@ -73,7 +68,7 @@ final class _ReporterForStdout extends Reporter implements SourceFileReporter, CodeSampleReporter { final Logger logger; - _ReporterForStdout({required super.verbose}) + _ReporterForStdout({required bool verbose}) : logger = Logger( (message, level) { if (verbose || LogLevel.debug != level) { @@ -126,7 +121,8 @@ final class _ReporterForStdout extends Reporter /// `package:test`. final class _RepoterForTest extends Reporter implements SourceFileReporter, CodeSampleReporter { - _RepoterForTest({required super.verbose}); + final bool _verbose; + _RepoterForTest({required bool verbose}) : _verbose = verbose; @override void reportSourceFile(String filename, diff --git a/dartdoc_test/test/testdata/dartdoc_test.txt b/dartdoc_test/test/testdata/dartdoc_test.txt index 0d0f268b..d376effe 100644 --- a/dartdoc_test/test/testdata/dartdoc_test.txt +++ b/dartdoc_test/test/testdata/dartdoc_test.txt @@ -9,7 +9,7 @@ Analyzing code samples ... │ ^ ╵ package:matcher fail - package:dartdoc_test/src/reporter.dart 167:13 _RepoterForTest._reportIssue. + package:dartdoc_test/src/reporter.dart 163:13 _RepoterForTest._reportIssue. 00:00 +0 -1: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for isPalindrome 00:00 +0 -2: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for isPalindrome [E] @@ -19,7 +19,7 @@ Analyzing code samples ... │ ^^^^^^^^^^^^ ╵ package:matcher fail - package:dartdoc_test/src/reporter.dart 167:13 _RepoterForTest._reportIssue. + package:dartdoc_test/src/reporter.dart 163:13 _RepoterForTest._reportIssue. 00:00 +0 -2: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for gcd 00:00 +0 -3: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for gcd [E] @@ -29,7 +29,7 @@ Analyzing code samples ... │ ^^^ ╵ package:matcher fail - package:dartdoc_test/src/reporter.dart 167:13 _RepoterForTest._reportIssue. + package:dartdoc_test/src/reporter.dart 163:13 _RepoterForTest._reportIssue. 00:00 +0 -3: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for length 00:00 +0 -4: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for length [E] @@ -39,7 +39,7 @@ Analyzing code samples ... │ ^^^^^^ ╵ package:matcher fail - package:dartdoc_test/src/reporter.dart 167:13 _RepoterForTest._reportIssue. + package:dartdoc_test/src/reporter.dart 163:13 _RepoterForTest._reportIssue. 00:00 +0 -4: Some tests failed. From 22e1ae32fba5321c94bedce60db6ba0873c8e880 Mon Sep 17 00:00:00 2001 From: takumma Date: Sun, 25 Aug 2024 10:19:10 +0900 Subject: [PATCH 20/23] add missing doc comment --- dartdoc_test/lib/src/model.dart | 1 + 1 file changed, 1 insertion(+) diff --git a/dartdoc_test/lib/src/model.dart b/dartdoc_test/lib/src/model.dart index 3848c410..fa9cf923 100644 --- a/dartdoc_test/lib/src/model.dart +++ b/dartdoc_test/lib/src/model.dart @@ -92,6 +92,7 @@ final class DocumentationCodeSample { required this.noTest, }); + /// Whether the code sample has a `main` function. bool get hasMain => code.contains('void main()'); /// Create a sample by wrapping the code with a main function and imports. From db64bdbac4587a7f166d08939babd68f19063fb0 Mon Sep 17 00:00:00 2001 From: takumma Date: Wed, 28 Aug 2024 19:35:32 +0900 Subject: [PATCH 21/23] fix output code --- dartdoc_test/lib/src/model.dart | 16 ++++++++++------ .../testdata/code_sample/error_example_0.dart | 1 - .../testdata/code_sample/error_example_1.dart | 1 - .../testdata/code_sample/error_example_2.dart | 1 - .../testdata/code_sample/error_example_3.dart | 1 - .../test/testdata/code_sample/example_0.dart | 1 - .../test/testdata/code_sample/example_1.dart | 1 - .../test/testdata/code_sample/example_2.dart | 1 - .../test/testdata/code_sample/example_3.dart | 1 - .../test/testdata/code_sample/example_5.dart | 9 ++++----- .../test/testdata/code_sample/example_6.dart | 13 ++++++------- ...lyze command by default with verbose flag.txt | 14 +++++++------- .../run analyze command with verbose flag.txt | 14 +++++++------- 13 files changed, 34 insertions(+), 40 deletions(-) diff --git a/dartdoc_test/lib/src/model.dart b/dartdoc_test/lib/src/model.dart index fa9cf923..8043d3c4 100644 --- a/dartdoc_test/lib/src/model.dart +++ b/dartdoc_test/lib/src/model.dart @@ -100,8 +100,8 @@ final class DocumentationCodeSample { final fileName = comment.span.sourceUrl; final buf = StringBuffer(); - buf.writeAll(comment.imports, '\n'); - buf.writeln(); + buf.writeAll(comment.imports); + if (comment.imports.isNotEmpty) buf.writeln(); if (fileName != null) { if (fileName.hasAbsolutePath) { final path = p.relative(fileName.path, from: testDir.absolute.path); @@ -111,10 +111,14 @@ final class DocumentationCodeSample { } } buf.writeln(); - if (!hasMain) buf.writeln('void main() {'); - buf.writeAll(LineSplitter.split(code).map((l) => ' $l'), '\n'); - buf.writeln(); - if (!hasMain) buf.writeln('}'); + if (!hasMain) { + buf.writeln('void main() {'); + buf.writeAll(LineSplitter.split(code).map((l) => ' $l'), '\n'); + buf.writeln(''); + buf.writeln('}'); + } else { + buf.write(code); + } return buf.toString(); } } diff --git a/dartdoc_test/test/testdata/code_sample/error_example_0.dart b/dartdoc_test/test/testdata/code_sample/error_example_0.dart index f6601413..3da9ea58 100644 --- a/dartdoc_test/test/testdata/code_sample/error_example_0.dart +++ b/dartdoc_test/test/testdata/code_sample/error_example_0.dart @@ -1,4 +1,3 @@ - import 'package:example/error_example.dart'; void main() { diff --git a/dartdoc_test/test/testdata/code_sample/error_example_1.dart b/dartdoc_test/test/testdata/code_sample/error_example_1.dart index 9d9afded..15493b11 100644 --- a/dartdoc_test/test/testdata/code_sample/error_example_1.dart +++ b/dartdoc_test/test/testdata/code_sample/error_example_1.dart @@ -1,4 +1,3 @@ - import 'package:example/error_example.dart'; void main() { diff --git a/dartdoc_test/test/testdata/code_sample/error_example_2.dart b/dartdoc_test/test/testdata/code_sample/error_example_2.dart index 05f0c310..d67b2581 100644 --- a/dartdoc_test/test/testdata/code_sample/error_example_2.dart +++ b/dartdoc_test/test/testdata/code_sample/error_example_2.dart @@ -1,4 +1,3 @@ - import 'package:example/error_example.dart'; void main() { diff --git a/dartdoc_test/test/testdata/code_sample/error_example_3.dart b/dartdoc_test/test/testdata/code_sample/error_example_3.dart index 1c9070cb..f887a659 100644 --- a/dartdoc_test/test/testdata/code_sample/error_example_3.dart +++ b/dartdoc_test/test/testdata/code_sample/error_example_3.dart @@ -1,4 +1,3 @@ - import 'package:example/error_example.dart'; void main() { diff --git a/dartdoc_test/test/testdata/code_sample/example_0.dart b/dartdoc_test/test/testdata/code_sample/example_0.dart index 94dedae7..615e5784 100644 --- a/dartdoc_test/test/testdata/code_sample/example_0.dart +++ b/dartdoc_test/test/testdata/code_sample/example_0.dart @@ -1,4 +1,3 @@ - import 'package:example/example.dart'; void main() { diff --git a/dartdoc_test/test/testdata/code_sample/example_1.dart b/dartdoc_test/test/testdata/code_sample/example_1.dart index 40fa4b5c..75f366b2 100644 --- a/dartdoc_test/test/testdata/code_sample/example_1.dart +++ b/dartdoc_test/test/testdata/code_sample/example_1.dart @@ -1,4 +1,3 @@ - import 'package:example/example.dart'; void main() { diff --git a/dartdoc_test/test/testdata/code_sample/example_2.dart b/dartdoc_test/test/testdata/code_sample/example_2.dart index c4324621..29401477 100644 --- a/dartdoc_test/test/testdata/code_sample/example_2.dart +++ b/dartdoc_test/test/testdata/code_sample/example_2.dart @@ -1,4 +1,3 @@ - import 'package:example/example.dart'; void main() { diff --git a/dartdoc_test/test/testdata/code_sample/example_3.dart b/dartdoc_test/test/testdata/code_sample/example_3.dart index 6ef62d04..63d2d97e 100644 --- a/dartdoc_test/test/testdata/code_sample/example_3.dart +++ b/dartdoc_test/test/testdata/code_sample/example_3.dart @@ -1,4 +1,3 @@ - import 'package:example/example.dart'; void main() { diff --git a/dartdoc_test/test/testdata/code_sample/example_5.dart b/dartdoc_test/test/testdata/code_sample/example_5.dart index 32878d87..fc54602e 100644 --- a/dartdoc_test/test/testdata/code_sample/example_5.dart +++ b/dartdoc_test/test/testdata/code_sample/example_5.dart @@ -1,7 +1,6 @@ - import 'package:example/example.dart'; - void main() { - final result = divide(10, 2); - print(result); // 5 - } +void main() { + final result = divide(10, 2); + print(result); // 5 +} diff --git a/dartdoc_test/test/testdata/code_sample/example_6.dart b/dartdoc_test/test/testdata/code_sample/example_6.dart index 57997e4f..84d3f963 100644 --- a/dartdoc_test/test/testdata/code_sample/example_6.dart +++ b/dartdoc_test/test/testdata/code_sample/example_6.dart @@ -1,9 +1,8 @@ - import 'package:example/example.dart'; - import 'dart:convert'; - - void main() { - final x = LineSplitter().convert('2\n3').map(int.parse).toList(); - print(pow(x[0], x[1])); // 8 - } +import 'dart:convert'; + +void main() { + final x = LineSplitter().convert('2\n3').map(int.parse).toList(); + print(pow(x[0], x[1])); // 8 +} diff --git a/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt b/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt index e5979cec..6f3935d1 100644 --- a/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt +++ b/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt @@ -1,35 +1,35 @@ $ dart run dartdoc_test -v Extracting code samples ... Analyzing code samples ... -original error: .dart_tool/dartdoc_test/error_example_0.dart:5:27: Expected to find ';'. +original error: .dart_tool/dartdoc_test/error_example_0.dart:4:27: Expected to find ';'. package:example/error_example.dart:17:29: : Expected to find ';'. ╷ 17 │ /// final fact = factorial(5) │ ^ ╵ -original error: .dart_tool/dartdoc_test/error_example_1.dart:5:24: Local variable 'isPalindrome' can't be referenced before it is declared. +original error: .dart_tool/dartdoc_test/error_example_1.dart:4:24: Local variable 'isPalindrome' can't be referenced before it is declared. package:example/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. ╷ 31 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); │ ^^^^^^^^^^^^ ╵ -.dart_tool/dartdoc_test/error_example_1.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) -original error: .dart_tool/dartdoc_test/error_example_2.dart:5:15: Local variable 'gcd' can't be referenced before it is declared. +.dart_tool/dartdoc_test/error_example_1.dart:1:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) +original error: .dart_tool/dartdoc_test/error_example_2.dart:4:15: Local variable 'gcd' can't be referenced before it is declared. package:example/error_example.dart:39:36: : Local variable 'gcd' can't be referenced before it is declared. ╷ 39 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. │ ^^^ ╵ -.dart_tool/dartdoc_test/error_example_2.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) -original error: .dart_tool/dartdoc_test/error_example_3.dart:5:20: The getter 'length' isn't defined for the type 'int'. +.dart_tool/dartdoc_test/error_example_2.dart:1:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) +original error: .dart_tool/dartdoc_test/error_example_3.dart:4:20: The getter 'length' isn't defined for the type 'int'. package:example/error_example.dart:53:32: : The getter 'length' isn't defined for the type 'int'. ╷ 53 │ /// Should return: The getter 'length' isn't defined for the class 'int'. │ ^^^^^^ ╵ -.dart_tool/dartdoc_test/error_example_3.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) +.dart_tool/dartdoc_test/error_example_3.dart:1:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) FAILED: 4 issues found (Found 10 code samples in 2 files) \ No newline at end of file diff --git a/dartdoc_test/test/testdata/run analyze command with verbose flag.txt b/dartdoc_test/test/testdata/run analyze command with verbose flag.txt index 80ea6407..755a32f4 100644 --- a/dartdoc_test/test/testdata/run analyze command with verbose flag.txt +++ b/dartdoc_test/test/testdata/run analyze command with verbose flag.txt @@ -1,35 +1,35 @@ $ dart run dartdoc_test analyze -v Extracting code samples ... Analyzing code samples ... -original error: .dart_tool/dartdoc_test/error_example_0.dart:5:27: Expected to find ';'. +original error: .dart_tool/dartdoc_test/error_example_0.dart:4:27: Expected to find ';'. package:example/error_example.dart:17:29: : Expected to find ';'. ╷ 17 │ /// final fact = factorial(5) │ ^ ╵ -original error: .dart_tool/dartdoc_test/error_example_1.dart:5:24: Local variable 'isPalindrome' can't be referenced before it is declared. +original error: .dart_tool/dartdoc_test/error_example_1.dart:4:24: Local variable 'isPalindrome' can't be referenced before it is declared. package:example/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. ╷ 31 │ /// final isPalindrome = isPalindrome('A man, a plan, a canal, Panama'); │ ^^^^^^^^^^^^ ╵ -.dart_tool/dartdoc_test/error_example_1.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) -original error: .dart_tool/dartdoc_test/error_example_2.dart:5:15: Local variable 'gcd' can't be referenced before it is declared. +.dart_tool/dartdoc_test/error_example_1.dart:1:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) +original error: .dart_tool/dartdoc_test/error_example_2.dart:4:15: Local variable 'gcd' can't be referenced before it is declared. package:example/error_example.dart:39:36: : Local variable 'gcd' can't be referenced before it is declared. ╷ 39 │ /// Should return: Local variable 'gcd' can't be referenced before it is declared. │ ^^^ ╵ -.dart_tool/dartdoc_test/error_example_2.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) -original error: .dart_tool/dartdoc_test/error_example_3.dart:5:20: The getter 'length' isn't defined for the type 'int'. +.dart_tool/dartdoc_test/error_example_2.dart:1:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) +original error: .dart_tool/dartdoc_test/error_example_3.dart:4:20: The getter 'length' isn't defined for the type 'int'. package:example/error_example.dart:53:32: : The getter 'length' isn't defined for the type 'int'. ╷ 53 │ /// Should return: The getter 'length' isn't defined for the class 'int'. │ ^^^^^^ ╵ -.dart_tool/dartdoc_test/error_example_3.dart:2:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) +.dart_tool/dartdoc_test/error_example_3.dart:1:8: Unused import: 'package:example/error_example.dart'. (ignored because issue occurs in the generated code) FAILED: 4 issues found (Found 10 code samples in 2 files) \ No newline at end of file From ebe3a8a9cac5a3b55ebc6538050f4891eb5a2c01 Mon Sep 17 00:00:00 2001 From: takumma Date: Wed, 28 Aug 2024 19:39:13 +0900 Subject: [PATCH 22/23] fix for ci --- dartdoc_test/example/lib/error_example.dart | 4 ++-- .../test/testdata/code_sample/error_example_0.dart | 2 +- dartdoc_test/test/testdata/dartdoc_test.txt | 6 +++--- .../run analyze command by default with verbose flag.txt | 8 ++++---- .../test/testdata/run analyze command by default.txt | 6 +++--- .../testdata/run analyze command with verbose flag.txt | 8 ++++---- dartdoc_test/test/testdata/run analyze command.txt | 6 +++--- 7 files changed, 20 insertions(+), 20 deletions(-) diff --git a/dartdoc_test/example/lib/error_example.dart b/dartdoc_test/example/lib/error_example.dart index 79953bb5..281a2866 100644 --- a/dartdoc_test/example/lib/error_example.dart +++ b/dartdoc_test/example/lib/error_example.dart @@ -12,9 +12,9 @@ // See the License for the specific language governing permissions and // limitations under the License. -/// Should return: Expected to find ';'. +/// 1 positional argument expected by 'factorial', but 0 found. /// ```dart -/// final fact = factorial(5) +/// final fact = factorial(); /// print(fact); // 120 /// ``` int factorial(int n) { diff --git a/dartdoc_test/test/testdata/code_sample/error_example_0.dart b/dartdoc_test/test/testdata/code_sample/error_example_0.dart index 3da9ea58..54647ece 100644 --- a/dartdoc_test/test/testdata/code_sample/error_example_0.dart +++ b/dartdoc_test/test/testdata/code_sample/error_example_0.dart @@ -1,6 +1,6 @@ import 'package:example/error_example.dart'; void main() { - final fact = factorial(5) + final fact = factorial(); print(fact); // 120 } diff --git a/dartdoc_test/test/testdata/dartdoc_test.txt b/dartdoc_test/test/testdata/dartdoc_test.txt index d376effe..21b53fb1 100644 --- a/dartdoc_test/test/testdata/dartdoc_test.txt +++ b/dartdoc_test/test/testdata/dartdoc_test.txt @@ -3,10 +3,10 @@ Extracting code samples ... Analyzing code samples ... 00:00 +0: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for ) 00:00 +0 -1: test/dartdoc_test.dart: [dartdoc_test] lib/error_example.dart test for ) [E] - package:example/error_example.dart:17:29: : Expected to find ';'. + package:example/error_example.dart:17:28: : 1 positional argument expected by 'factorial', but 0 found. ╷ - 17 │ /// final fact = factorial(5) - │ ^ + 17 │ /// final fact = factorial(); + │ ^ ╵ package:matcher fail package:dartdoc_test/src/reporter.dart 163:13 _RepoterForTest._reportIssue. diff --git a/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt b/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt index 6f3935d1..607299fe 100644 --- a/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt +++ b/dartdoc_test/test/testdata/run analyze command by default with verbose flag.txt @@ -1,11 +1,11 @@ $ dart run dartdoc_test -v Extracting code samples ... Analyzing code samples ... -original error: .dart_tool/dartdoc_test/error_example_0.dart:4:27: Expected to find ';'. -package:example/error_example.dart:17:29: : Expected to find ';'. +original error: .dart_tool/dartdoc_test/error_example_0.dart:4:26: 1 positional argument expected by 'factorial', but 0 found. +package:example/error_example.dart:17:28: : 1 positional argument expected by 'factorial', but 0 found. ╷ -17 │ /// final fact = factorial(5) - │ ^ +17 │ /// final fact = factorial(); + │ ^ ╵ original error: .dart_tool/dartdoc_test/error_example_1.dart:4:24: Local variable 'isPalindrome' can't be referenced before it is declared. diff --git a/dartdoc_test/test/testdata/run analyze command by default.txt b/dartdoc_test/test/testdata/run analyze command by default.txt index 5bd5002a..3253226c 100644 --- a/dartdoc_test/test/testdata/run analyze command by default.txt +++ b/dartdoc_test/test/testdata/run analyze command by default.txt @@ -1,10 +1,10 @@ $ dart run dartdoc_test Extracting code samples ... Analyzing code samples ... -package:example/error_example.dart:17:29: : Expected to find ';'. +package:example/error_example.dart:17:28: : 1 positional argument expected by 'factorial', but 0 found. ╷ -17 │ /// final fact = factorial(5) - │ ^ +17 │ /// final fact = factorial(); + │ ^ ╵ package:example/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. diff --git a/dartdoc_test/test/testdata/run analyze command with verbose flag.txt b/dartdoc_test/test/testdata/run analyze command with verbose flag.txt index 755a32f4..f0b7fb5f 100644 --- a/dartdoc_test/test/testdata/run analyze command with verbose flag.txt +++ b/dartdoc_test/test/testdata/run analyze command with verbose flag.txt @@ -1,11 +1,11 @@ $ dart run dartdoc_test analyze -v Extracting code samples ... Analyzing code samples ... -original error: .dart_tool/dartdoc_test/error_example_0.dart:4:27: Expected to find ';'. -package:example/error_example.dart:17:29: : Expected to find ';'. +original error: .dart_tool/dartdoc_test/error_example_0.dart:4:26: 1 positional argument expected by 'factorial', but 0 found. +package:example/error_example.dart:17:28: : 1 positional argument expected by 'factorial', but 0 found. ╷ -17 │ /// final fact = factorial(5) - │ ^ +17 │ /// final fact = factorial(); + │ ^ ╵ original error: .dart_tool/dartdoc_test/error_example_1.dart:4:24: Local variable 'isPalindrome' can't be referenced before it is declared. diff --git a/dartdoc_test/test/testdata/run analyze command.txt b/dartdoc_test/test/testdata/run analyze command.txt index e21e9ca5..116295a2 100644 --- a/dartdoc_test/test/testdata/run analyze command.txt +++ b/dartdoc_test/test/testdata/run analyze command.txt @@ -1,10 +1,10 @@ $ dart run dartdoc_test analyze Extracting code samples ... Analyzing code samples ... -package:example/error_example.dart:17:29: : Expected to find ';'. +package:example/error_example.dart:17:28: : 1 positional argument expected by 'factorial', but 0 found. ╷ -17 │ /// final fact = factorial(5) - │ ^ +17 │ /// final fact = factorial(); + │ ^ ╵ package:example/error_example.dart:31:11: : Local variable 'isPalindrome' can't be referenced before it is declared. From 4b2ffa2f720ab8a2da33bdaf8dbf6cf57655d39f Mon Sep 17 00:00:00 2001 From: takumma Date: Wed, 28 Aug 2024 19:46:13 +0900 Subject: [PATCH 23/23] fix readme --- dartdoc_test/README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/dartdoc_test/README.md b/dartdoc_test/README.md index 11df4eb8..69177687 100644 --- a/dartdoc_test/README.md +++ b/dartdoc_test/README.md @@ -28,6 +28,9 @@ dart run dartdoc_test By creating `test/dartdoc_test.dart`, you can test code samples with using the `dart test` command. ```bash +# 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