[analyzer] Add some more diagnostic code generation features.

The following features are added:

- The ability to exclude a generated error class from the generated
  `diagnosticCodeValues` list.

- The ability for the code generator to add a documentation comment at
  the top of the generated error class.

These features are not used yet. In follow-up CLs, I will be switching
some error classes over to code generation, and that will require
these features.

Change-Id: I6a6a696408ac8498ef6cd9a053b3a82005378789
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/445280
Reviewed-by: Brian Wilkerson <brianwilkerson@google.com>
Reviewed-by: Konstantin Shcheglov <scheglov@google.com>
Commit-Queue: Paul Berry <paulberry@google.com>

Author: stereotype441

pkg/analyzer/tool/messages/error_code_info.dart

@@ -507,6 +507,15 @@ class ErrorClassInfo {
   /// notice) after migration to camel case error codes.
   final Set<String> deprecatedSnakeCaseNames;
 
+  /// If `true` (the default), error codes of this class will be included in the
+  /// automatically-generated `diagnosticCodeValues` list.
+  final bool includeInDiagnosticCodeValues;
+
+  /// Documentation comment to generate for the error class.
+  ///
+  /// If no documentation comment is needed, this should be the empty string.
+  final String comment;
+
   const ErrorClassInfo({
     this.extraImports = const [],
     required this.file,
@@ -516,6 +525,8 @@ class ErrorClassInfo {
     this.superclass = 'DiagnosticCode',
     required this.type,
     this.deprecatedSnakeCaseNames = const {},
+    this.includeInDiagnosticCodeValues = true,
+    this.comment = '',
   });
 
   /// Generates the code to compute the severity of errors of this class.
@@ -868,9 +879,12 @@ class GeneratedErrorCodeFile {
   /// constructor invocations.
   final bool shouldUseExplicitConst;
 
+  final bool shouldIgnorePreferSingleQuotes;
+
   const GeneratedErrorCodeFile({
     required this.path,
     required this.preferredImportUri,
     this.shouldUseExplicitConst = false,
+    this.shouldIgnorePreferSingleQuotes = false,
   });
 }

pkg/analyzer/tool/messages/generate.dart

@@ -87,15 +87,20 @@ class _AnalyzerErrorGenerator {
 
 // While transitioning `HintCodes` to `WarningCodes`, we refer to deprecated
 // codes here.
-// ignore_for_file: deprecated_member_use_from_same_package
-// 
-// Generated comments don't quite align with flutter style.
-// ignore_for_file: flutter_style_todos
 ''');
 
   _AnalyzerErrorGenerator(this.file, this.errorClasses, this.generatedCodes);
 
   void generate() {
+    out.writeln('// ignore_for_file: deprecated_member_use_from_same_package');
+    if (file.shouldIgnorePreferSingleQuotes) {
+      out.writeln('// ignore_for_file: prefer_single_quotes');
+    }
+    out.write('''
+// 
+// Generated comments don't quite align with flutter style.
+// ignore_for_file: flutter_style_todos
+''');
     out.writeln();
     out.write('''
 /// @docImport 'package:analyzer/src/dart/error/syntactic_errors.g.dart';
@@ -132,6 +137,11 @@ library;
     for (var errorClass
         in errorClasses.toList()..sort((a, b) => a.name.compareTo(b.name))) {
       out.writeln();
+      if (errorClass.comment.isNotEmpty) {
+        errorClass.comment.trimRight().split('\n').forEach((line) {
+          out.writeln('/// $line');
+        });
+      }
       out.write('class ${errorClass.name} extends ${errorClass.superclass} {');
       var entries = [
         ...analyzerMessages[errorClass.name]!.entries,
@@ -155,7 +165,9 @@ library;
             );
             out.writeln('${errorCodeInfo.aliasFor};');
           } else {
-            generatedCodes.add((errorClass.name, errorName));
+            if (errorClass.includeInDiagnosticCodeValues) {
+              generatedCodes.add((errorClass.name, errorName));
+            }
             var constantName = errorName.toCamelCase();
             out.writeln('  static const ${errorClass.name} $constantName =');
             out.writeln(