Skip to content

Commit 7c1ca3f

Browse files
szakariasdart-scoped@luci-project-accounts.iam.gserviceaccount.com
authored andcommitted
[analyzer] Add minimal parsing support for {@example} doc directive
Change-Id: I332e69894817a061bf678a1314a2b78bfaaf56a1 Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/518300 Reviewed-by: Johnni Winther <[email protected]> Commit-Queue: Brian Wilkerson <[email protected]> Reviewed-by: Brian Wilkerson <[email protected]> Auto-Submit: Sarah Zakarias <[email protected]>
1 parent d6d92b8 commit 7c1ca3f

4 files changed

Lines changed: 69 additions & 0 deletions

File tree

‎pkg/analyzer/api.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1846,6 +1846,7 @@ package:analyzer/dart/ast/doc_comment.dart:
18461846
endInjectHtml (static getter: DocDirectiveType)
18471847
endTemplate (static getter: DocDirectiveType)
18481848
endTool (static getter: DocDirectiveType)
1849+
example (static getter: DocDirectiveType)
18491850
injectHtml (static getter: DocDirectiveType)
18501851
macro (static getter: DocDirectiveType)
18511852
subCategory (static getter: DocDirectiveType)

‎pkg/analyzer/lib/dart/ast/doc_comment.dart‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -304,6 +304,18 @@ enum DocDirectiveType {
304304
restParametersAllowed: true,
305305
),
306306

307+
/// A [DocDirective] declaring an example.
308+
///
309+
/// See documentation at
310+
/// <https://github.com/dart-lang/dartdoc/blob/main/doc/directives.md#example>.
311+
example(
312+
'example',
313+
positionalParameters: [
314+
DocDirectiveParameter('file', DocDirectiveParameterFormat.any),
315+
],
316+
restParametersAllowed: true,
317+
),
318+
307319
/// A [DocDirective] declaring an embedded YouTube video.
308320
///
309321
/// This directive has three required arguments: the width, the height, and

‎pkg/analyzer/lib/src/fasta/doc_comment_builder.dart‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -382,6 +382,9 @@ final class DocCommentBuilder {
382382
case 'endtemplate':
383383
_endBlockDocDirectiveTag(parser, DocDirectiveType.endTemplate);
384384
return true;
385+
case 'example':
386+
_pushDocDirective(parser.simpleDirective(DocDirectiveType.example));
387+
return true;
385388
case 'inject-html':
386389
_parseBlockDocDirectiveTag(parser, DocDirectiveType.injectHtml);
387390
return true;

‎pkg/analyzer/test/src/dart/parser/doc_comment_test.dart‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -845,6 +845,59 @@ Comment
845845
''');
846846
}
847847

848+
test_exampleDirective() {
849+
var parseResult = parseTestCodeWithDiagnostics(r'''
850+
int x = 0;
851+
852+
/// Text.
853+
/// {@example /path/to/file.dart#region}
854+
class A {}
855+
''');
856+
857+
var node = parseResult.findNode.comment('example');
858+
assertParsedNodeText(node, r'''
859+
Comment
860+
tokens
861+
/// Text.
862+
/// {@example /path/to/file.dart#region}
863+
docDirectives
864+
SimpleDocDirective
865+
tag
866+
offset: [26, 63]
867+
type: [DocDirectiveType.example]
868+
positionalArguments
869+
/path/to/file.dart#region
870+
''');
871+
}
872+
873+
test_exampleDirective_args() {
874+
var parseResult = parseTestCodeWithDiagnostics(r'''
875+
int x = 0;
876+
877+
/// Text.
878+
/// {@example /path/to/file.dart#region lang=dart indent=keep}
879+
class A {}
880+
''');
881+
882+
var node = parseResult.findNode.comment('example');
883+
assertParsedNodeText(node, r'''
884+
Comment
885+
tokens
886+
/// Text.
887+
/// {@example /path/to/file.dart#region lang=dart indent=keep}
888+
docDirectives
889+
SimpleDocDirective
890+
tag
891+
offset: [26, 85]
892+
type: [DocDirectiveType.example]
893+
positionalArguments
894+
/path/to/file.dart#region
895+
namedArguments
896+
lang=dart
897+
indent=keep
898+
''');
899+
}
900+
848901
test_fencedCodeBlock_blockComment() {
849902
var parseResult = parseTestCodeWithDiagnostics(r'''
850903
/**

0 commit comments

Comments
 (0)