[analyzer/linter] Clean up error message comments.

This change modifies the comments in the analyzer and linter
`messages.yaml` files so that:

- Parameters are always described at the end of the comment. If the
  message takes no parameters, the comment ends with the text `No
  parameters.`

- Parameter descriptions are always word wrapped to 80 columns.

It also fixes the format of the comment field for
`ANALYSIS_OPTION_DEPRECATED` to remove an unintentional blank line,
and adds documentation for the second parameter of
`INVALID_EXPORT_OF_INTERNAL_ELEMENT_INDIRECTLY` (which was previously
missing).

In a follow-up CL, I will transition to a more structured format for
parameters in these `messages.yaml` files, and the `Parameters:`
sections of the comments will be automatically generated from this
structured format during code generation. Cleaning up the comments now
will ensure that the follow-up CL is clean (makes no changes to
generated files), so we'll be able to have high confidence in its
correctness.

Change-Id: I6aa1f75fa0b8e4fb9724dcba00fb7d1f06dfb355
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/444205
Reviewed-by: Johnni Winther <[email protected]>
Commit-Queue: Paul Berry <[email protected]>
Reviewed-by: Konstantin Shcheglov <[email protected]>
Reviewed-by: Phil Quitslund <[email protected]>

Author: stereotype441

pkg/_fe_analyzer_shared/lib/src/scanner/errors.g.dart

@@ -41,21 +41,25 @@ class ScannerErrorCode extends DiagnosticCode {
     "Illegal character '{0}'.",
   );
 
+  /// No parameters.
   static const ScannerErrorCode MISSING_DIGIT = const ScannerErrorCode(
     'MISSING_DIGIT',
     "Decimal digit expected.",
   );
 
+  /// No parameters.
   static const ScannerErrorCode MISSING_HEX_DIGIT = const ScannerErrorCode(
     'MISSING_HEX_DIGIT',
     "Hexadecimal digit expected.",
   );
 
+  /// No parameters.
   static const ScannerErrorCode MISSING_IDENTIFIER = const ScannerErrorCode(
     'MISSING_IDENTIFIER',
     "Expected an identifier.",
   );
 
+  /// No parameters.
   static const ScannerErrorCode MISSING_QUOTE = const ScannerErrorCode(
     'MISSING_QUOTE',
     "Expected quote (' or \").",
@@ -68,6 +72,7 @@ class ScannerErrorCode extends DiagnosticCode {
     "Unable to get content of '{0}'.",
   );
 
+  /// No parameters.
   static const ScannerErrorCode
   UNEXPECTED_DOLLAR_IN_STRING = const ScannerErrorCode(
     'UNEXPECTED_DOLLAR_IN_STRING',
@@ -76,6 +81,7 @@ class ScannerErrorCode extends DiagnosticCode {
     correctionMessage: "Try adding a backslash (\\) to escape the '\$'.",
   );
 
+  /// No parameters.
   static const ScannerErrorCode
   UNEXPECTED_SEPARATOR_IN_NUMBER = const ScannerErrorCode(
     'UNEXPECTED_SEPARATOR_IN_NUMBER',
@@ -91,6 +97,7 @@ class ScannerErrorCode extends DiagnosticCode {
     "The '{0}' operator is not supported.",
   );
 
+  /// No parameters.
   static const ScannerErrorCode UNTERMINATED_MULTI_LINE_COMMENT =
       const ScannerErrorCode(
         'UNTERMINATED_MULTI_LINE_COMMENT',
@@ -100,6 +107,7 @@ class ScannerErrorCode extends DiagnosticCode {
             "occurrences of '/*' (because comments nest in Dart).",
       );
 
+  /// No parameters.
   static const ScannerErrorCode UNTERMINATED_STRING_LITERAL =
       const ScannerErrorCode(
         'UNTERMINATED_STRING_LITERAL',

pkg/analyzer/lib/src/analysis_options/error/option_codes.g.dart

@@ -76,7 +76,6 @@ class AnalysisOptionsWarningCode extends DiagnosticCode {
   ///
   /// Parameters:
   /// 0: the option name
-  ///
   static const AnalysisOptionsWarningCode ANALYSIS_OPTION_DEPRECATED =
       AnalysisOptionsWarningCode(
         'ANALYSIS_OPTION_DEPRECATED',

pkg/analyzer/lib/src/dart/error/ffi_code.g.dart

@@ -105,7 +105,7 @@ class FfiCode extends DiagnosticCode {
     hasPublishedDocs: true,
   );
 
-  /// No parameters
+  /// No parameters.
   static const FfiCode ARGUMENT_MUST_BE_NATIVE = FfiCode(
     'ARGUMENT_MUST_BE_NATIVE',
     "Argument to 'Native.addressOf' must be annotated with @Native",
@@ -161,15 +161,15 @@ class FfiCode extends DiagnosticCode {
     hasPublishedDocs: true,
   );
 
-  /// No parameters
+  /// No parameters.
   static const FfiCode FFI_NATIVE_INVALID_DUPLICATE_DEFAULT_ASSET = FfiCode(
     'FFI_NATIVE_INVALID_DUPLICATE_DEFAULT_ASSET',
     "There may be at most one @DefaultAsset annotation on a library.",
     correctionMessage: "Try removing the extra annotation.",
     hasPublishedDocs: true,
   );
 
-  /// No parameters
+  /// No parameters.
   static const FfiCode FFI_NATIVE_INVALID_MULTIPLE_ANNOTATIONS = FfiCode(
     'FFI_NATIVE_INVALID_MULTIPLE_ANNOTATIONS',
     "Native functions and fields must have exactly one `@Native` annotation.",
@@ -373,7 +373,7 @@ class FfiCode extends DiagnosticCode {
     hasPublishedDocs: true,
   );
 
-  /// No parameters
+  /// No parameters.
   static const FfiCode NATIVE_FIELD_MISSING_TYPE = FfiCode(
     'NATIVE_FIELD_MISSING_TYPE',
     "The native type of this field could not be inferred and must be specified "
@@ -384,15 +384,15 @@ class FfiCode extends DiagnosticCode {
     hasPublishedDocs: true,
   );
 
-  /// No parameters
+  /// No parameters.
   static const FfiCode NATIVE_FIELD_NOT_STATIC = FfiCode(
     'NATIVE_FIELD_NOT_STATIC',
     "Native fields must be static.",
     correctionMessage: "Try adding the modifier 'static' to this field.",
     hasPublishedDocs: true,
   );
 
-  /// No parameters
+  /// No parameters.
   static const FfiCode NATIVE_FUNCTION_MISSING_TYPE = FfiCode(
     'NATIVE_FUNCTION_MISSING_TYPE',
     "The native type of this function couldn't be inferred so it must be "

pkg/analyzer/lib/src/dart/error/hint_codes.g.dart

@@ -27,10 +27,10 @@ library;
 import "package:_fe_analyzer_shared/src/base/errors.dart";
 
 class HintCode extends DiagnosticCode {
-  /// No parameters.
-  ///
   /// Note: Since this diagnostic is only produced in pre-3.0 code, we do not
   /// plan to go through the exercise of converting it to a Warning.
+  ///
+  /// No parameters.
   static const HintCode DEPRECATED_COLON_FOR_DEFAULT_VALUE = HintCode(
     'DEPRECATED_COLON_FOR_DEFAULT_VALUE',
     "Using a colon as the separator before a default value is deprecated and "
@@ -49,11 +49,11 @@ class HintCode extends DiagnosticCode {
     hasPublishedDocs: true,
   );
 
-  /// Parameters:
-  /// 0: the name of the member
-  ///
   /// This code is deprecated in favor of the
   /// 'deprecated_member_from_same_package' lint rule, and will be removed.
+  ///
+  /// Parameters:
+  /// 0: the name of the member
   static const HintCode DEPRECATED_MEMBER_USE_FROM_SAME_PACKAGE = HintCode(
     'DEPRECATED_MEMBER_USE_FROM_SAME_PACKAGE',
     "'{0}' is deprecated and shouldn't be used.",
@@ -62,12 +62,12 @@ class HintCode extends DiagnosticCode {
     hasPublishedDocs: true,
   );
 
+  /// This code is deprecated in favor of the
+  /// 'deprecated_member_from_same_package' lint rule, and will be removed.
+  ///
   /// Parameters:
   /// 0: the name of the member
   /// 1: message details
-  ///
-  /// This code is deprecated in favor of the
-  /// 'deprecated_member_from_same_package' lint rule, and will be removed.
   static const HintCode
   DEPRECATED_MEMBER_USE_FROM_SAME_PACKAGE_WITH_MESSAGE = HintCode(
     'DEPRECATED_MEMBER_USE_FROM_SAME_PACKAGE',