Deprecate the missingCodeBlockLanguage warning. (#3743)

* Deprecate the missingCodeBlockLanguage warning.

* Added a stderr warning.

* Add a copyright msg.

* Write error on warn and error warnings that are deprecated.

* Generalize warning oops.

Author: kallentu

lib/src/model/documentation_comment.dart

@@ -1,3 +1,7 @@
+// Copyright (c) 2024, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
 import 'package:analyzer/dart/element/element.dart';
 import 'package:args/args.dart';
 import 'package:crypto/crypto.dart' as crypto;

lib/src/warnings.dart

@@ -279,16 +279,19 @@ enum PackageWarning implements Comparable<PackageWarning> {
     'deprecated dartdoc usage: {0}',
     shortHelp: 'A dartdoc directive has a deprecated format.',
   ),
+  // TODO(kallentu): Remove this warning.
   missingCodeBlockLanguage(
     'missing-code-block-language',
     'missing code block language: {0}',
-    shortHelp: 'A fenced code block is missing a specified language.',
-    longHelp:
-        'To enable proper syntax highlighting of Markdown code blocks, Dartdoc '
-        'requires code blocks to specify the language used after the initial '
-        'declaration. As an example, to specify Dart you would open the '
-        'Markdown code block with ```dart or ~~~dart.',
+    shortHelp: '(Deprecated: Use `missing_code_block_language_in_doc_comment` '
+        'lint) A fenced code block is missing a specified language.',
+    longHelp: '(Deprecated: Use `missing_code_block_language_in_doc_comment` '
+        'lint) To enable proper syntax highlighting of Markdown code blocks, '
+        'Dartdoc requires code blocks to specify the language used after the '
+        'initial declaration. As an example, to specify Dart you would open '
+        'the Markdown code block with ```dart or ~~~dart.',
     defaultWarningMode: PackageWarningMode.ignore,
+    isDeprecated: true,
   );
 
   /// The name which can be used at the command line to enable this warning.
@@ -305,6 +308,8 @@ enum PackageWarning implements Comparable<PackageWarning> {
 
   final String _longHelp;
 
+  final bool _isDeprecated;
+
   final PackageWarningMode _defaultWarningMode;
 
   const PackageWarning(
@@ -314,11 +319,13 @@ enum PackageWarning implements Comparable<PackageWarning> {
     String longHelp = '',
     String warnablePrefix = 'from',
     String referredFromPrefix = 'referred to by',
+    bool isDeprecated = false,
     PackageWarningMode defaultWarningMode = PackageWarningMode.warn,
   })  : _shortHelp = shortHelp,
         _longHelp = longHelp,
         _warnablePrefix = warnablePrefix,
         _referredFromPrefix = referredFromPrefix,
+        _isDeprecated = isDeprecated,
         _defaultWarningMode = defaultWarningMode;
 
   static PackageWarning? _byName(String name) =>
@@ -402,6 +409,7 @@ class PackageWarningOptions {
     for (var warningName in errorsForDir) {
       var packageWarning = PackageWarning._byName(warningName);
       if (packageWarning != null) {
+        newOptions.writeErrorOnDeprecation(packageWarning);
         newOptions.error(packageWarning);
       }
     }
@@ -410,6 +418,7 @@ class PackageWarningOptions {
     for (var warningName in warningsForDir) {
       var packageWarning = PackageWarning._byName(warningName);
       if (packageWarning != null) {
+        newOptions.writeErrorOnDeprecation(packageWarning);
         newOptions.warn(packageWarning);
       }
     }
@@ -455,14 +464,20 @@ class PackageWarningOptions {
     return newOptions;
   }
 
+  void error(PackageWarning kind) =>
+      warningModes[kind] = PackageWarningMode.error;
+
   void ignore(PackageWarning kind) =>
       warningModes[kind] = PackageWarningMode.ignore;
 
   void warn(PackageWarning kind) =>
       warningModes[kind] = PackageWarningMode.warn;
 
-  void error(PackageWarning kind) =>
-      warningModes[kind] = PackageWarningMode.error;
+  void writeErrorOnDeprecation(PackageWarning warning) {
+    if (warning._isDeprecated) {
+      stderr.writeln("The warning '${warning._flagName}' is deprecated.");
+    }
+  }
 
   PackageWarningMode getMode(PackageWarning kind) => warningModes[kind]!;
 }