Switch from using "while" to "end" and adjust nested rules accordingly (

#75) * Add additional tests for unclosed code blocks in comments * Switch from using "while" to "end" and adjust nested rules accordingly * Update date * Update date in changelog
dart-lang · Nov 18, 2024 · 5b36228 · 5b36228
1 parent d3bc5c4
commit 5b36228
Show file tree

Hide file tree

Showing 5 changed files with 237 additions and 49 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,8 @@
+## 1.4.0 (2024-11-14)
+
+- Removed use of 'while' in the grammar to avoid some differences in implementations between GitHub and VS Code
+- Improved handling of unclosed code blocks in dartdoc comments
+
 ## 1.3.0 (2024-07-31)
 
 - Added support for digit separators (`_`).

diff --git a/grammars/dart.json b/grammars/dart.json
@@ -1,6 +1,6 @@
 {
 	"name": "Dart",
-	"version": "1.3.0",
+	"version": "1.4.0",
 	"fileTypes": [
 		"dart"
 	],
@@ -69,6 +69,16 @@
 	],
 
 	"repository": {
+		"dartdoc-codeblock-triple": {
+			"begin": "^\\s*///\\s*(?!\\s*```)",
+			"end": "\n",
+			"contentName": "variable.other.source.dart"
+		},
+		"dartdoc-codeblock-block": {
+			"begin": "^\\s*\\*\\s*(?!(\\s*```|\/))",
+			"end": "\n",
+			"contentName": "variable.other.source.dart"
+		},
 		"dartdoc": {
 			"patterns": [
 				{
@@ -80,30 +90,31 @@
 					}
 				},
 				{
-					"match": "^ {4,}(?![ \\*]).*",
-					"captures": {
-						"0": {
-							"name": "variable.name.source.dart"
+					"begin": "^\\s*///\\s*(```)",
+					"end": "^\\s*///\\s*(```)|^(?!\\s*///)",
+					"patterns": [
+						{
+							"include": "#dartdoc-codeblock-triple"
 						}
-					}
+					]
 				},
 				{
-					"contentName": "variable.other.source.dart",
-					"begin": "```.*?$",
-					"end": "```"
+					"begin": "^\\s*\\*\\s*(```)",
+					"end": "^\\s*\\*\\s*(```)|^(?=\\s*\\*\/)",
+					"patterns": [
+						{
+							"include": "#dartdoc-codeblock-block"
+						}
+					]
 				},
 				{
-					"match": "(`[^`]+?`)",
-					"captures": {
-						"0": {
-							"name": "variable.other.source.dart"
-						}
-					}
+					"match": "`[^`\n]+`",
+					"name": "variable.other.source.dart"
 				},
 				{
-					"match": "(\\* ((    ).*))$",
+					"match": "\\s{4,}(.*)$",
 					"captures": {
-						"2": {
+						"1": {
 							"name": "variable.other.source.dart"
 						}
 					}
@@ -157,7 +168,7 @@
 				{
 					"name": "comment.block.documentation.dart",
 					"begin": "///",
-					"while": "^\\s*///",
+					"end": "^(?!\\s*///)",
 					"patterns": [
 						{
 							"include": "#dartdoc"

diff --git a/pubspec.yaml b/pubspec.yaml
@@ -4,8 +4,8 @@ environment:
   sdk: ^3.2.0
 
 dev_dependencies:
-  collection: ^1.18.0
-  dart_flutter_team_lints: ^2.1.1
+  collection: ^1.19.0
+  dart_flutter_team_lints: ^3.2.1
   path: ^1.9.0
-  string_scanner: ^1.2.0
-  test: ^1.25.2
+  string_scanner: ^1.4.0
+  test: ^1.25.8
diff --git a/test/goldens/comments.dart.golden b/test/goldens/comments.dart.golden
@@ -5,26 +5,143 @@
 >// found in the LICENSE file.
 #^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ comment.line.double-slash.dart
 >
->/// Multiline dartdoc comment.
-#^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ comment.block.documentation.dart
+>/// Multiline dartdoc comment with triple backticks.
+#^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ comment.block.documentation.dart
 >///
 #^^^ comment.block.documentation.dart
 >/// ```
 #^^^^^^^ comment.block.documentation.dart
->/// doc
+>/// code
+#^^^^ comment.block.documentation.dart
+#    ^^^^ comment.block.documentation.dart variable.other.source.dart
+>/// ```
+#^^^^^^^ comment.block.documentation.dart
+>///
+#^^^ comment.block.documentation.dart
+>/// ...
+#^^^^^^^ comment.block.documentation.dart
+>var doc1;
+#^^^ storage.type.primitive.dart
+#        ^ punctuation.terminator.dart
+>
+>/// Multiline dartdoc comment with unclosed triple backticks.
+#^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ comment.block.documentation.dart
+>///
 #^^^ comment.block.documentation.dart
-#   ^^^^ comment.block.documentation.dart variable.other.source.dart
 >/// ```
+#^^^^^^^ comment.block.documentation.dart
+>/// code
+#^^^^ comment.block.documentation.dart
+#    ^^^^ comment.block.documentation.dart variable.other.source.dart
+>var doc2;
+#^^^ storage.type.primitive.dart
+#        ^ punctuation.terminator.dart
+>
+>/// Multiline dartdoc comment with unclosed backticks.
+#^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ comment.block.documentation.dart
+>///
 #^^^ comment.block.documentation.dart
-#   ^ comment.block.documentation.dart variable.other.source.dart
-#    ^^^ comment.block.documentation.dart
+>/// `code
+#^^^^^^^^^ comment.block.documentation.dart
+>var doc3;
+#^^^ storage.type.primitive.dart
+#        ^ punctuation.terminator.dart
+>
+>/// Multiline dartdoc comment with indented code.
+#^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ comment.block.documentation.dart
+>///
+#^^^ comment.block.documentation.dart
+>///     code1
+#^^^^^^^^ comment.block.documentation.dart
+#        ^^^^^ comment.block.documentation.dart variable.other.source.dart
+>///     code2
+#^^^^^^^^ comment.block.documentation.dart
+#        ^^^^^ comment.block.documentation.dart variable.other.source.dart
+>///
+#^^^ comment.block.documentation.dart
+>///     code3
+#^^^^^^^^ comment.block.documentation.dart
+#        ^^^^^ comment.block.documentation.dart variable.other.source.dart
 >///
 #^^^ comment.block.documentation.dart
 >/// ...
 #^^^^^^^ comment.block.documentation.dart
->var a;
+>var doc4;
 #^^^ storage.type.primitive.dart
-#     ^ punctuation.terminator.dart
+#        ^ punctuation.terminator.dart
+>
+>/** Block dartdoc comment with triple backticks.
+#^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ comment.block.documentation.dart
+> *
+#^^ comment.block.documentation.dart
+> * ```
+#^^^^^^ comment.block.documentation.dart
+> * code
+#^^^ comment.block.documentation.dart
+#   ^^^^ comment.block.documentation.dart variable.other.source.dart
+> * ```
+#^^^^^^ comment.block.documentation.dart
+> *
+#^^ comment.block.documentation.dart
+> * ...
+#^^^^^^ comment.block.documentation.dart
+> */
+#^^^ comment.block.documentation.dart
+>var blockDoc1;
+#^^^ storage.type.primitive.dart
+#             ^ punctuation.terminator.dart
+>
+>/** Block dartdoc comment with unclosed triple backticks.
+#^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ comment.block.documentation.dart
+> *
+#^^ comment.block.documentation.dart
+> * ```
+#^^^^^^ comment.block.documentation.dart
+> * code
+#^^^ comment.block.documentation.dart
+#   ^^^^ comment.block.documentation.dart variable.other.source.dart
+> */
+#^^^ comment.block.documentation.dart
+>var blockDoc2;
+#^^^ storage.type.primitive.dart
+#             ^ punctuation.terminator.dart
+>
+>/** Block dartdoc comment with unclosed backticks.
+#^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ comment.block.documentation.dart
+> *
+#^^ comment.block.documentation.dart
+> * `code
+#^^^^^^^^ comment.block.documentation.dart
+> */
+#^^^ comment.block.documentation.dart
+>var blockDoc3;
+#^^^ storage.type.primitive.dart
+#             ^ punctuation.terminator.dart
+>
+>/** Block dartdoc comment with indented code.
+#^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ comment.block.documentation.dart
+> *
+#^^ comment.block.documentation.dart
+> *     code1
+#^^^^^^^ comment.block.documentation.dart
+#       ^^^^^ comment.block.documentation.dart variable.other.source.dart
+> *     code2
+#^^^^^^^ comment.block.documentation.dart
+#       ^^^^^ comment.block.documentation.dart variable.other.source.dart
+> *
+#^^ comment.block.documentation.dart
+> *     code3
+#^^^^^^^ comment.block.documentation.dart
+#       ^^^^^ comment.block.documentation.dart variable.other.source.dart
+> *
+#^^ comment.block.documentation.dart
+> * ...
+#^^^^^^ comment.block.documentation.dart
+> */
+#^^^ comment.block.documentation.dart
+>var blockDoc4;
+#^^^ storage.type.primitive.dart
+#             ^ punctuation.terminator.dart
 >
 >/// ``
 #^^^^^^ comment.block.documentation.dart
@@ -123,24 +240,24 @@
 #^^^ storage.type.primitive.dart
 #     ^ punctuation.terminator.dart
 >
->class A<dynamic /* comment */ > {
+>class A<T /* comment */ > {
 #^^^^^ keyword.declaration.dart
 #      ^ support.class.dart
 #       ^ other.source.dart
-#        ^^^^^^^ support.class.dart
-#                ^^^^^^^^^^^^^ comment.block.dart
-#                              ^ other.source.dart
->  void b<dynamic /* comment */ >() {}
+#        ^ support.class.dart
+#          ^^^^^^^^^^^^^ comment.block.dart
+#                        ^ other.source.dart
+>  void b<T /* comment */ >() {}
 #  ^^^^ storage.type.primitive.dart
 #        ^ keyword.operator.comparison.dart
-#         ^^^^^^^ support.class.dart
-#                 ^^^^^^^^^^^^^ comment.block.dart
-#                               ^ keyword.operator.comparison.dart
->  Future<dynamic /* comment */ > c() {}
+#         ^ support.class.dart
+#           ^^^^^^^^^^^^^ comment.block.dart
+#                         ^ keyword.operator.comparison.dart
+>  Future<T /* comment */ > c() {}
 #  ^^^^^^ support.class.dart
 #        ^ other.source.dart
-#         ^^^^^^^ support.class.dart
-#                 ^^^^^^^^^^^^^ comment.block.dart
-#                               ^ other.source.dart
-#                                 ^ entity.name.function.dart
+#         ^ support.class.dart
+#           ^^^^^^^^^^^^^ comment.block.dart
+#                         ^ other.source.dart
+#                           ^ entity.name.function.dart
 >}
diff --git a/test/test_files/comments.dart b/test/test_files/comments.dart
@@ -2,14 +2,69 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-/// Multiline dartdoc comment.
+/// Multiline dartdoc comment with triple backticks.
 ///
 /// ```
-/// doc
+/// code
 /// ```
 ///
 /// ...
-var a;
+var doc1;
+
+/// Multiline dartdoc comment with unclosed triple backticks.
+///
+/// ```
+/// code
+var doc2;
+
+/// Multiline dartdoc comment with unclosed backticks.
+///
+/// `code
+var doc3;
+
+/// Multiline dartdoc comment with indented code.
+///
+///     code1
+///     code2
+///
+///     code3
+///
+/// ...
+var doc4;
+
+/** Block dartdoc comment with triple backticks.
+ *
+ * ```
+ * code
+ * ```
+ *
+ * ...
+ */
+var blockDoc1;
+
+/** Block dartdoc comment with unclosed triple backticks.
+ *
+ * ```
+ * code
+ */
+var blockDoc2;
+
+/** Block dartdoc comment with unclosed backticks.
+ *
+ * `code
+ */
+var blockDoc3;
+
+/** Block dartdoc comment with indented code.
+ *
+ *     code1
+ *     code2
+ *
+ *     code3
+ *
+ * ...
+ */
+var blockDoc4;
 
 /// ``
 var noInlineCode;
@@ -56,7 +111,7 @@ var g;
 /// And a link to [example.org](http://example.org/).
 var h;
 
-class A<dynamic /* comment */ > {
-  void b<dynamic /* comment */ >() {}
-  Future<dynamic /* comment */ > c() {}
+class A<T /* comment */ > {
+  void b<T /* comment */ >() {}
+  Future<T /* comment */ > c() {}
 }