Improve error messages and add many corrections

pkg/analyzer/lib/error/error.dart

 // Copyright (c) 2014, 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.
 
 library analyzer.error.error;
 
 import 'dart:collection';
 
 import 'package:analyzer/dart/element/element.dart';
 import 'package:analyzer/error/listener.dart';
@@ skipping 217 matching lines @@
   void setProperty/*<V>*/(ErrorProperty/*<V>*/ property, Object/*=V*/ value) {
     _propertyMap[property] = value;
   }
 }
 
 /**
  * An error code associated with an [AnalysisError].
  *
  * Generally, we want to provide messages that consist of three sentences. From
  * the user's perspective these sentences should explain:
+ *
  * 1. what is wrong,
  * 2. why is it wrong, and
  * 3. how do I fix it.
+ *
  * However, we combine the first two in the [message] and the last in the
  * [correction].
+ *
+ * When composing messages (including correction messages) keep the following
+ * guidelines in mind.
+ *
+ * 1. The message should be a complete sentence starting with an uppercase
+ * letter, and ending with a period.
+ *
+ * 2. Reserved words and embedded identifiers should be in single quotes, so
+ * prefer double quotes for the complete message. For example,
+ * ```
+ * "The class '{0}' can't use 'super'."
+ * ```
+ * Notice that the word 'class' in the preceding message is not quoted as it
+ * refers to the concept 'class', not the reserved word. On the other hand,
+ * 'super' refers to the reserved word. Do not quote 'null' and numeric literals.
+ *
+ * 3. Do not try to compose messages, as it can make translating them hard.
+ *
+ * 4. Try to keep the error messages short, but informative.
+ *
+ * 5. Use simple words and terminology, assume the reader of the message doesn't
+ * have an advanced degree in math, and that English is not the reader's native
+ * language. Do not assume any formal computer science training. For example, do
+ * not use Latin abbreviations (prefer "that is" over "i.e.", and "for example"
+ * over "e.g."). Also avoid phrases such as "if and only if" and "iff"; that
+ * level of precision is unnecessary.
+ *
+ * 6. Prefer contractions when they are in common use, for example, prefer
+ * "can't" over "cannot". Using "cannot", "must not", "shall not", etc. is
+ * off-putting to people new to programming.
+ *
+ * 7. Use common terminology, preferably from the Dart Language Specification.
+ * This increases the user's chance of finding a good explanation on the web.
+ *
+ * 8. Do not try to be cute or funny. It is extremely frustrating to work on a
+ * product that crashes with a "tongue-in-cheek" message, especially if you did
+ * not want to use this product to begin with.
+ *
+ * 9. Do not lie, that is, do not write error messages containing phrases like
+ * "can't happen".  If the user ever saw this message, it would be a lie. Prefer
+ * messages like: "Internal error: This function should not be called when 'x'
+ * is null.".
+ *
+ * 10. Prefer to not use the imperative tone. That is, the message should not
+ * sound accusing or like it is ordering the user around. The computer should
+ * describe the problem, not criticize the user for violating the specification.
  */
 abstract class ErrorCode {
   /**
    * Engine error code values.
    */
   static const List<ErrorCode> values = const [
     //
     // Manually generated.  FWIW, this get's you most of the way there:
     //
     // > grep 'static const .*Code' (error.dart|parser|scanner.dart)
@@ skipping 17 matching lines @@
     CompileTimeErrorCode.AMBIGUOUS_EXPORT,
     CompileTimeErrorCode.ANNOTATION_WITH_NON_CLASS,
     CompileTimeErrorCode.ARGUMENT_DEFINITION_TEST_NON_PARAMETER,
     CompileTimeErrorCode.ASYNC_FOR_IN_WRONG_CONTEXT,
     CompileTimeErrorCode.AWAIT_IN_WRONG_CONTEXT,
     CompileTimeErrorCode.BUILT_IN_IDENTIFIER_AS_TYPE,
     CompileTimeErrorCode.BUILT_IN_IDENTIFIER_AS_TYPE_NAME,
     CompileTimeErrorCode.BUILT_IN_IDENTIFIER_AS_TYPEDEF_NAME,
     CompileTimeErrorCode.BUILT_IN_IDENTIFIER_AS_TYPE_PARAMETER_NAME,
     CompileTimeErrorCode.CASE_EXPRESSION_TYPE_IMPLEMENTS_EQUALS,
-    CompileTimeErrorCode.COMPILE_TIME_CONSTANT_RAISES_EXCEPTION,
     CompileTimeErrorCode.CONFLICTING_GETTER_AND_METHOD,
     CompileTimeErrorCode.CONFLICTING_METHOD_AND_GETTER,
     CompileTimeErrorCode.CONFLICTING_CONSTRUCTOR_NAME_AND_FIELD,
     CompileTimeErrorCode.CONFLICTING_CONSTRUCTOR_NAME_AND_METHOD,
     CompileTimeErrorCode.CONFLICTING_TYPE_VARIABLE_AND_CLASS,
     CompileTimeErrorCode.CONFLICTING_TYPE_VARIABLE_AND_MEMBER,
     CompileTimeErrorCode.CONST_CONSTRUCTOR_THROWS_EXCEPTION,
     CompileTimeErrorCode.CONST_CONSTRUCTOR_WITH_FIELD_INITIALIZED_BY_NON_CONST,
     CompileTimeErrorCode.CONST_CONSTRUCTOR_WITH_MIXIN,
     CompileTimeErrorCode.CONST_CONSTRUCTOR_WITH_NON_CONST_SUPER,
@@ skipping 201 matching lines @@
     HintCode.FILE_IMPORT_OUTSIDE_LIB_REFERENCES_FILE_INSIDE,
     HintCode.PACKAGE_IMPORT_CONTAINS_DOT_DOT,
     HtmlErrorCode.PARSE_ERROR,
     HtmlWarningCode.INVALID_URI,
     HtmlWarningCode.URI_DOES_NOT_EXIST,
     StaticTypeWarningCode.EXPECTED_ONE_LIST_TYPE_ARGUMENTS,
     StaticTypeWarningCode.EXPECTED_TWO_MAP_TYPE_ARGUMENTS,
     StaticTypeWarningCode.ILLEGAL_ASYNC_GENERATOR_RETURN_TYPE,
     StaticTypeWarningCode.ILLEGAL_ASYNC_RETURN_TYPE,
     StaticTypeWarningCode.ILLEGAL_SYNC_GENERATOR_RETURN_TYPE,
-    StaticTypeWarningCode.INACCESSIBLE_SETTER,
     StaticTypeWarningCode.INCONSISTENT_METHOD_INHERITANCE,
     StaticTypeWarningCode.INSTANCE_ACCESS_TO_STATIC_MEMBER,
     StaticTypeWarningCode.INVALID_ASSIGNMENT,
     StaticTypeWarningCode.INVOCATION_OF_NON_FUNCTION,
     StaticTypeWarningCode.INVOCATION_OF_NON_FUNCTION_EXPRESSION,
     StaticTypeWarningCode.NON_BOOL_CONDITION,
     StaticTypeWarningCode.NON_BOOL_EXPRESSION,
     StaticTypeWarningCode.NON_BOOL_NEGATION_EXPRESSION,
     StaticTypeWarningCode.NON_BOOL_OPERAND,
     StaticTypeWarningCode.NON_NULLABLE_FIELD_NOT_INITIALIZED,
@@ skipping 142 matching lines @@
     // parser.dart:
     //
     ParserErrorCode.ABSTRACT_CLASS_MEMBER,
     ParserErrorCode.ABSTRACT_ENUM,
     ParserErrorCode.ABSTRACT_STATIC_METHOD,
     ParserErrorCode.ABSTRACT_TOP_LEVEL_FUNCTION,
     ParserErrorCode.ABSTRACT_TOP_LEVEL_VARIABLE,
     ParserErrorCode.ABSTRACT_TYPEDEF,
     ParserErrorCode.ANNOTATION_ON_ENUM_CONSTANT,
     ParserErrorCode.ASYNC_KEYWORD_USED_AS_IDENTIFIER,
-    ParserErrorCode.ASYNC_NOT_SUPPORTED,
     ParserErrorCode.BREAK_OUTSIDE_OF_LOOP,
     ParserErrorCode.CLASS_IN_CLASS,
     ParserErrorCode.COLON_IN_PLACE_OF_IN,
     ParserErrorCode.CONST_AND_FINAL,
     ParserErrorCode.CONST_AND_VAR,
     ParserErrorCode.CONST_CLASS,
     ParserErrorCode.CONST_CONSTRUCTOR_WITH_BODY,
     ParserErrorCode.CONST_ENUM,
     ParserErrorCode.CONST_FACTORY,
     ParserErrorCode.CONST_METHOD,
@@ skipping 433 matching lines @@
 
   @override
   int get hashCode => ordinal;
 
   @override
   int compareTo(ErrorType other) => ordinal - other.ordinal;
 
   @override
   String toString() => name;
 }