update analysis option comments (#5785)

This aligns the comments and fixes some misspellings in the three related analysis options files.
There will be a follow on PR with more controversial changes to the repo level analysis options.

.analysis_options

 # Specify analysis options.
-
+#
+# Until there are meta linter rules, each desired lint must be explicitly enabled.
+# See: https://github.com/dart-lang/linter/issues/288
+#
+# For a list of lints, see: http://dart-lang.github.io/linter/lints/
+# See the configuration guide for more
+# https://github.com/dart-lang/sdk/tree/master/pkg/analyzer#configuring-the-analyzer
+#
 # This file contains the analysis options used by Flutter editors, such as Atom.
 # It is very similar to .analysis_options_flutter_analyze;
 # the only difference (currently) is the public_member_api_docs option,
@@ -11,25 +18,26 @@ analyzer:
     enableSuperMixins: true
   strong-mode: true
   errors:
-    # we allow overriding fields (if they use super, ideally...)
+    # allow overriding fields (if they use super, ideally...)
     strong_mode_invalid_field_override: ignore
-    # we allow type narrowing
+    # allow type narrowing
     strong_mode_invalid_method_override: ignore
     strong_mode_static_type_error: ignore
     strong_mode_down_cast_composite: ignore
-    # we allow having TODOs in the code
+    # allow having TODOs in the code
     todo: ignore
   exclude:
     - 'bin/**'
 
 linter:
   rules:
-    # these are in the same order as http://dart-lang.github.io/linter/lints/
-    # to make maintenance easier
+    # these rules are documented on and in the same order as
+    # the Dart Lint rules page to make maintenance easier
+    # http://dart-lang.github.io/linter/lints/
 
-    # error rules
+    # === error rules ===
     - avoid_empty_else
-    # - comment_references
+    # - comment_references # blocked on https://github.com/dart-lang/dartdoc/issues/1153
     - control_flow_in_finally
     - hash_and_equals
     # - iterable_contains_unrelated_type
@@ -37,7 +45,7 @@ linter:
     - throw_in_finally
     - unrelated_type_equality_checks
 
-    # style rules
+    # === style rules ===
     - always_declare_return_types
     - always_specify_types
     - annotate_overrides
@@ -46,7 +54,7 @@ linter:
     - avoid_return_types_on_setters
     - await_only_futures
     - camel_case_types
-    # - constant_identifier_names
+    # - constant_identifier_names # https://github.com/dart-lang/linter/issues/204
     - control_flow_in_finally
     - empty_constructor_bodies
     - implementation_imports
@@ -54,7 +62,7 @@ linter:
     - library_prefixes
     - non_constant_identifier_names
     - one_member_abstracts
-    # - overriden_field
+    # - overridden_fields
     - package_api_docs
     - package_prefixed_library_names
     - prefer_is_not_empty
@@ -68,5 +76,5 @@ linter:
     - unnecessary_brace_in_string_interp
     - unnecessary_getters_setters
 
-    # pub rules
+    # === pub rules ===
     - package_names

.analysis_options_flutter_analyze

 # Specify analysis options.
-
-# This file contains the analysis options used by 'flutter analyze'.
-# It is very similar to .analysis_options;
+#
+# Until there are meta linter rules, each desired lint must be explicitly enabled.
+# See: https://github.com/dart-lang/linter/issues/288
+#
+# For a list of lints, see: http://dart-lang.github.io/linter/lints/
+# See the configuration guide for more
+# https://github.com/dart-lang/sdk/tree/master/pkg/analyzer#configuring-the-analyzer
+#
+# This file contains the analysis options used by 'flutter analyze' when analyzing
+# the flutter repository. It is very similar to .analysis_options;
 # the only difference (currently) is the public_member_api_docs option,
 # which is turned on and programmatically reduced to a single output line
 # indicating the # of violations for that rule.
@@ -12,25 +19,26 @@ analyzer:
     enableSuperMixins: true
   strong-mode: true
   errors:
-    # we allow overriding fields (if they use super, ideally...)
+    # allow overriding fields (if they use super, ideally...)
     strong_mode_invalid_field_override: ignore
-    # we allow type narrowing
+    # allow type narrowing
     strong_mode_invalid_method_override: ignore
     strong_mode_static_type_error: ignore
     strong_mode_down_cast_composite: ignore
-    # we allow having TODOs in the code
+    # allow having TODOs in the code
     todo: ignore
   exclude:
     - 'bin/**'
 
 linter:
   rules:
-    # these are in the same order as http://dart-lang.github.io/linter/lints/
-    # to make maintenance easier
+    # these rules are documented on and in the same order as
+    # the Dart Lint rules page to make maintenance easier
+    # http://dart-lang.github.io/linter/lints/
 
-    # error rules
+    # === error rules ===
     - avoid_empty_else
-    # - comment_references
+    # - comment_references # blocked on https://github.com/dart-lang/dartdoc/issues/1153
     - control_flow_in_finally
     - hash_and_equals
     # - iterable_contains_unrelated_type
@@ -38,7 +46,7 @@ linter:
     - throw_in_finally
     - unrelated_type_equality_checks
 
-    # style rules
+    # === style rules ===
     - always_declare_return_types
     - always_specify_types
     - annotate_overrides
@@ -47,7 +55,7 @@ linter:
     - avoid_return_types_on_setters
     - await_only_futures
     - camel_case_types
-    # - constant_identifier_names
+    # - constant_identifier_names # https://github.com/dart-lang/linter/issues/204
     - control_flow_in_finally
     - empty_constructor_bodies
     - implementation_imports
@@ -55,7 +63,7 @@ linter:
     - library_prefixes
     - non_constant_identifier_names
     - one_member_abstracts
-    # - overriden_field
+    # - overridden_fields
     - package_api_docs
     - package_prefixed_library_names
     - prefer_is_not_empty
@@ -69,5 +77,5 @@ linter:
     - unnecessary_brace_in_string_interp
     - unnecessary_getters_setters
 
-    # pub rules
+    # === pub rules ===
     - package_names

packages/flutter_tools/flutter_analysis_options

@@ -7,9 +7,9 @@
 # See the configuration guide for more
 # https://github.com/dart-lang/sdk/tree/master/pkg/analyzer#configuring-the-analyzer
 #
-# This file is the .analysis_options file used by "flutter analyze"
+# This file contains the analysis options used by "flutter analyze"
 # when analyzing code outside the flutter repository.
-# It isn't named that because otherwise editors like Atom
+# It isn't named '.analysis_options' because otherwise editors like Atom
 # would use it when analyzing the flutter tool itself.
 #
 # When editing, make sure you keep /.analysis_options consistent.
@@ -45,8 +45,8 @@ linter:
     - hash_and_equals
     # - invariant_booleans
     # - iterable_contains_unrelated_type
-    # - list_remove_unrelated_typ
-    # - literal_only_boolean_expressionse
+    # - list_remove_unrelated_type
+    # - literal_only_boolean_expressions
     - test_types_in_equals
     - throw_in_finally
     - unrelated_type_equality_checks
@@ -69,7 +69,7 @@ linter:
     - non_constant_identifier_names
     # - one_member_abstracts
     # - only_throw_errors
-    # - overriden_fields
+    # - overridden_fields
     - package_api_docs
     - package_prefixed_library_names
     - prefer_is_not_empty