Warn if the user did not specify a language on the fenced code block

Author: parlough

lib/src/model/documentation_comment.dart

@@ -61,11 +61,15 @@ mixin DocumentationComment
   String processCommentWithoutTools(String documentationComment) {
     var docs = stripComments(documentationComment);
     if (!docs.contains('{@')) {
+      _analyzeCodeBlocks(docs);
       return docs;
     }
     docs = _injectExamples(docs);
     docs = _injectYouTube(docs);
     docs = _injectAnimations(docs);
+
+    _analyzeCodeBlocks(docs);
+
     // TODO(srawlins): Processing templates here causes #2281. But leaving them
     // unprocessed causes #2272.
     docs = _stripHtmlAndAddToIndex(docs);
@@ -79,6 +83,7 @@ mixin DocumentationComment
     // Must evaluate tools first, in case they insert any other directives.
     docs = await _evaluateTools(docs);
     docs = processCommentDirectives(docs);
+    _analyzeCodeBlocks(docs);
     return docs;
   }
 
@@ -673,4 +678,27 @@ mixin DocumentationComment
       return '$option${match[0]}';
     });
   }
+
+  static final _codeBlockPattern =
+      RegExp(r'^[ ]{0,3}(`{3,}|~{3,})(.*)$', multiLine: true);
+
+  /// Analyze fenced code blocks present in the documentation comment,
+  /// warning if there is no language specified.
+  void _analyzeCodeBlocks(String docs) {
+    final results = _codeBlockPattern.allMatches(docs).toList(growable: false);
+    final firstOfPair = <Match>[];
+    for (var i = 0; i < results.length; i++) {
+      if (i.isEven && i != results.length - 1) {
+        firstOfPair.add(results[i]);
+      }
+    }
+    firstOfPair.forEach((element) {
+      final result = element.group(2).trim();
+      if (result.isEmpty) {
+        warn(PackageWarning.missingCodeBlockLanguage,
+            message:
+                'A fenced code block in Markdown should have a language specified.');
+      }
+    });
+  }
 }

lib/src/warnings.dart

@@ -306,6 +306,7 @@ enum PackageWarning {
   unresolvedExport,
   missingConstantConstructor,
   missingExampleFile,
+  missingCodeBlockLanguage,
 }
 
 /// Used to declare defaults for a particular package warning.

test/documentation_comment_test.dart

@@ -844,6 +844,67 @@ Text.
               'Supported YouTube URLs have the following format: '
               'https://www.youtube.com/watch?v=oHg5SJYRHA0.'));
     });
+
+    test('warns when fenced code block does not specify language', () async {
+      await libraryModel.processComment('''
+/// ```
+/// void main() {}
+/// ```
+''');
+
+      expect(
+          packageGraph.packageWarningCounter.hasWarning(
+              libraryModel,
+              PackageWarning.missingCodeBlockLanguage,
+              'A fenced code block in Markdown should have a language specified.'),
+          isTrue);
+    });
+
+    test('warns when squiggly fenced code block does not specify language',
+        () async {
+      await libraryModel.processComment('''
+/// ~~~
+/// void main() {}
+/// ~~~
+''');
+
+      expect(
+          packageGraph.packageWarningCounter.hasWarning(
+              libraryModel,
+              PackageWarning.missingCodeBlockLanguage,
+              'A fenced code block in Markdown should have a language specified.'),
+          isTrue);
+    });
+
+    test('does not warn when fenced code block does specify language',
+        () async {
+      await libraryModel.processComment('''
+/// ```dart
+/// void main() {}
+/// ```
+''');
+
+      expect(
+          packageGraph.packageWarningCounter.hasWarning(
+              libraryModel,
+              PackageWarning.missingCodeBlockLanguage,
+              'A fenced code block in Markdown should have a language specified.'),
+          isFalse);
+    });
+
+    test('does not warn when fenced block is not closed', () async {
+      await libraryModel.processComment('''
+/// ```
+/// A not closed fenced code block
+''');
+
+      expect(
+          packageGraph.packageWarningCounter.hasWarning(
+              libraryModel,
+              PackageWarning.missingCodeBlockLanguage,
+              'A fenced code block in Markdown should have a language specified.'),
+          isFalse);
+    });
   }, onPlatform: {
     'windows': Skip('These tests do not work on Windows (#2446)')
   });