Make lint descriptions more consistently use code-quotes.

Use markdown code quotes for keywords and types.
Rephrase some descriptions as drive-by-fixups.

Change-Id: I9a54b19c00b8076c7999b21d209f92c2a4191644
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/365460
Commit-Queue: Lasse Nielsen <[email protected]>
Reviewed-by: Samuel Rawlins <[email protected]>

Author: lrhn

pkg/linter/lib/src/rules/avoid_annotating_with_dynamic.dart

@@ -9,10 +9,10 @@ import 'package:analyzer/dart/element/type.dart';
 import '../analyzer.dart';
 import '../extensions.dart';
 
-const _desc = r'Avoid annotating with dynamic when not required.';
+const _desc = r'Avoid annotating with `dynamic` when not required.';
 
 const _details = r'''
-**AVOID** annotating with dynamic when not required.
+**AVOID** annotating with `dynamic` when not required.
 
 As `dynamic` is the assumed return value of a function or method, it is usually
 not necessary to annotate it.

pkg/linter/lib/src/rules/avoid_bool_literals_in_conditional_expressions.dart

@@ -7,10 +7,10 @@ import 'package:analyzer/dart/ast/visitor.dart';
 
 import '../analyzer.dart';
 
-const _desc = r'Avoid bool literals in conditional expressions.';
+const _desc = r'Avoid `bool` literals in conditional expressions.';
 
 const _details = r'''
-**AVOID** bool literals in conditional expressions.
+**AVOID** `bool` literals in conditional expressions.
 
 **BAD:**
 ```dart

pkg/linter/lib/src/rules/avoid_catching_errors.dart

@@ -8,10 +8,10 @@ import 'package:analyzer/dart/ast/visitor.dart';
 import '../analyzer.dart';
 import '../extensions.dart';
 
-const _desc = r"Don't explicitly catch Error or types that implement it.";
+const _desc = r"Don't explicitly catch `Error` or types that implement it.";
 
 const _details = r'''
-**DON'T** explicitly catch Error or types that implement it.
+**DON'T** explicitly catch `Error` or types that implement it.
 
 Errors differ from Exceptions in that Errors can be analyzed and prevented prior
 to runtime.  It should almost never be necessary to catch an error at runtime.

pkg/linter/lib/src/rules/avoid_double_and_int_checks.dart

@@ -8,10 +8,10 @@ import 'package:analyzer/dart/element/element.dart';
 
 import '../analyzer.dart';
 
-const _desc = r'Avoid double and int checks.';
+const _desc = r'Avoid `double` and `int` checks.';
 
 const _details = r'''
-**AVOID** to check if type is double or int.
+**AVOID** to check if type is `double` or `int`.
 
 When compiled to JS, integer values are represented as floats. That can lead to
 some unexpected behavior when using either `is` or `is!` where the type is

pkg/linter/lib/src/rules/avoid_dynamic_calls.dart

@@ -9,31 +9,31 @@ import 'package:analyzer/dart/element/type.dart';
 
 import '../analyzer.dart';
 
-const _desc = r'Avoid method calls or property accesses on a "dynamic" target.';
+const _desc = r'Avoid method calls or property accesses on a `dynamic` target.';
 
 const _details = r'''
 **DO** avoid method calls or accessing properties on an object that is either
-explicitly or implicitly statically typed "dynamic". Dynamic calls are treated
+explicitly or implicitly statically typed `dynamic`. Dynamic calls are treated
 slightly different in every runtime environment and compiler, but most
 production modes (and even some development modes) have both compile size and
 runtime performance penalties associated with dynamic calls.
 
-Additionally, targets typed "dynamic" disables most static analysis, meaning it
-is easier to lead to a runtime "NoSuchMethodError" or "NullError" than properly
+Additionally, targets typed `dynamic` disables most static analysis, meaning it
+is easier to lead to a runtime `NoSuchMethodError` or `TypeError` than properly
 statically typed Dart code.
 
-There is an exception to methods and properties that exist on "Object?":
-- a.hashCode
-- a.runtimeType
-- a.noSuchMethod(someInvocation)
-- a.toString()
+There is an exception to methods and properties that exist on `Object?`:
+- `a.hashCode`
+- `a.runtimeType`
+- `a.noSuchMethod(someInvocation)`
+- `a.toString()`
 
 ... these members are dynamically dispatched in the web-based runtimes, but not
 in the VM-based ones. Additionally, they are so common that it would be very
 punishing to disallow `any.toString()` or `any == true`, for example.
 
-Note that despite "Function" being a type, the semantics are close to identical
-to "dynamic", and calls to an object that is typed "Function" will also trigger
+Note that despite `Function` being a type, the semantics are close to identical
+to `dynamic`, and calls to an object that is typed `Function` will also trigger
 this lint.
 
 Dynamic calls are allowed on cast expressions (`as dynamic` or `as Function`).

pkg/linter/lib/src/rules/avoid_final_parameters.dart

@@ -7,13 +7,13 @@ import 'package:analyzer/dart/ast/visitor.dart';
 
 import '../analyzer.dart';
 
-const _desc = r'Avoid final for parameter declarations.';
+const _desc = r'Avoid `final` for parameter declarations.';
 
 const _details = r'''
-**AVOID** declaring parameters as final.
+**AVOID** declaring parameters as `final`.
 
-Declaring parameters as final can lead to unnecessarily verbose code, especially
-when using the "parameter_assignments" rule.
+Declaring parameters as `final` can lead to unnecessarily verbose code,
+especially when using the "parameter_assignments" rule.
 
 **BAD:**
 ```dart

pkg/linter/lib/src/rules/avoid_init_to_null.dart

@@ -10,19 +10,19 @@ import 'package:analyzer/dart/element/type.dart';
 import '../analyzer.dart';
 import '../extensions.dart';
 
-const _desc = r"Don't explicitly initialize variables to null.";
+const _desc = r"Don't explicitly initialize variables to `null`.";
 
 const _details = r'''
 From [Effective Dart](https://dart.dev/effective-dart/usage#dont-explicitly-initialize-variables-to-null):
 
 **DON'T** explicitly initialize variables to `null`.
 
-If a variable has a non-nullable type or is `final`, 
+If a variable has a non-nullable type or is `final`,
 Dart reports a compile error if you try to use it
-before it has been definitely initialized. 
-If the variable is nullable and not `const` or `final`, 
-then it is implicitly initialized to `null` for you. 
-There's no concept of "uninitialized memory" in Dart 
+before it has been definitely initialized.
+If the variable is nullable and not `const` or `final`,
+then it is implicitly initialized to `null` for you.
+There's no concept of "uninitialized memory" in Dart
 and no need to explicitly initialize a variable to `null` to be "safe".
 Adding `= null` is redundant and unneeded.
 

pkg/linter/lib/src/rules/avoid_null_checks_in_equality_operators.dart

@@ -11,14 +11,14 @@ import 'package:analyzer/dart/element/nullability_suffix.dart';
 import '../analyzer.dart';
 import '../extensions.dart';
 
-const _desc = r"Don't check for null in custom == operators.";
+const _desc = r"Don't check for `null` in custom `==` operators.";
 
 const _details = r'''
-**DON'T** check for null in custom == operators.
+**DON'T** check for `null` in custom `==` operators.
 
-As null is a special value, no instance of any class (other than `Null`) can be
-equivalent to it.  Thus, it is redundant to check whether the other instance is
-null.
+As `null` is a special value, no instance of any class (other than `Null`) can
+be equivalent to it.  Thus, it is redundant to check whether the other instance
+is `null`.
 
 **BAD:**
 ```dart

pkg/linter/lib/src/rules/avoid_returning_null_for_void.dart

@@ -8,10 +8,10 @@ import 'package:analyzer/dart/element/type.dart';
 
 import '../analyzer.dart';
 
-const _desc = r'Avoid returning null for void.';
+const _desc = r'Avoid returning `null` for `void`.';
 
 const _details = r'''
-**AVOID** returning null for void.
+**AVOID** returning `null` for `void`.
 
 In a large variety of languages `void` as return type is used to indicate that
 a function doesn't return anything. Dart allows returning `null` in functions

pkg/linter/lib/src/rules/avoid_slow_async_io.dart

@@ -10,7 +10,7 @@ import 'package:analyzer/dart/element/type.dart';
 import '../analyzer.dart';
 import '../extensions.dart';
 
-const _desc = r'Avoid slow async `dart:io` methods.';
+const _desc = r'Avoid slow asynchronous `dart:io` methods.';
 
 const _details = r'''
 **AVOID** using the following asynchronous file I/O methods because they are

pkg/linter/lib/src/rules/avoid_void_async.dart

@@ -10,12 +10,12 @@ import 'package:analyzer/dart/element/type.dart';
 
 import '../analyzer.dart';
 
-const _desc = r'Avoid async functions that return void.';
+const _desc = r'Avoid `async` functions that return `void`.';
 
 const _details = r'''
-**DO** mark async functions as returning `Future<void>`.
+**DO** mark `async` functions as returning `Future<void>`.
 
-When declaring an async method or function which does not return a value,
+When declaring an `async` method or function which does not return a value,
 declare that it returns `Future<void>` and not just `void`.
 
 **BAD:**

pkg/linter/lib/src/rules/cancel_subscriptions.dart

@@ -8,10 +8,10 @@ import '../analyzer.dart';
 import '../extensions.dart';
 import '../util/leak_detector_visitor.dart';
 
-const _desc = r'Cancel instances of dart.async.StreamSubscription.';
+const _desc = r'Cancel instances of `dart:async` `StreamSubscription`.';
 
 const _details = r'''
-**DO** invoke `cancel` on instances of `dart.async.StreamSubscription`.
+**DO** invoke `cancel` on instances of `dart:async` `StreamSubscription`.
 
 Cancelling instances of StreamSubscription prevents memory leaks and unexpected
 behavior.

pkg/linter/lib/src/rules/close_sinks.dart

@@ -8,10 +8,10 @@ import '../analyzer.dart';
 import '../extensions.dart';
 import '../util/leak_detector_visitor.dart';
 
-const _desc = r'Close instances of `dart.core.Sink`.';
+const _desc = r'Close instances of `dart:core` `Sink`.';
 
 const _details = r'''
-**DO** invoke `close` on instances of `dart.core.Sink`.
+**DO** invoke `close` on instances of `dart:core` `Sink`.
 
 Closing instances of Sink prevents memory leaks and unexpected behavior.
 

pkg/linter/lib/src/rules/control_flow_in_finally.dart

@@ -7,12 +7,12 @@ import 'package:analyzer/dart/ast/visitor.dart';
 
 import '../analyzer.dart';
 
-const _desc = r'Avoid control flow in finally blocks.';
+const _desc = r'Avoid control flow in `finally` blocks.';
 
 const _details = r'''
-**AVOID** control flow leaving finally blocks.
+**AVOID** control flow leaving `finally` blocks.
 
-Using control flow in finally blocks will inevitably cause unexpected behavior
+Using control flow in `finally` blocks will inevitably cause unexpected behavior
 that is hard to debug.
 
 **BAD:**

pkg/linter/lib/src/rules/discarded_futures.dart

@@ -9,7 +9,7 @@ import 'package:analyzer/dart/element/type.dart';
 
 import '../analyzer.dart';
 
-const _desc = r"Don't invoke asynchronous functions in non-async blocks.";
+const _desc = r"Don't invoke asynchronous functions in non-`async` blocks.";
 
 const _details = r'''
 Making asynchronous calls in non-`async` functions is usually the sign of a

pkg/linter/lib/src/rules/iterable_contains_unrelated_type.dart

@@ -4,8 +4,8 @@
 
 import '../analyzer.dart';
 
-const _desc = r'Invocation of Iterable<E>.contains with references of unrelated'
-    r' types.';
+const _desc = r'Invocation of `Iterable<E>.contains` with references of'
+    r' unrelated types.';
 
 const _details = r'''
 NOTE: This rule is removed in Dart 3.3.0; it is no longer functional.

pkg/linter/lib/src/rules/no_runtimeType_toString.dart

@@ -10,7 +10,7 @@ import 'package:analyzer/dart/element/type.dart';
 
 import '../analyzer.dart';
 
-const _desc = r'Avoid calling toString() on runtimeType.';
+const _desc = r'Avoid calling `toString()` on `runtimeType`.';
 
 const _details = r'''
 Calling `toString` on a runtime type is a non-trivial operation that can

pkg/linter/lib/src/rules/null_check_on_nullable_type_parameter.dart

@@ -10,13 +10,14 @@ import 'package:analyzer/dart/element/type.dart';
 import '../analyzer.dart';
 import 'unnecessary_null_checks.dart';
 
-const _desc = r"Don't use null check on a potentially nullable type parameter.";
+const _desc =
+    r"Don't use `null` check on a potentially nullable type parameter.";
 
 const _details = r'''
-**DON'T** use null check on a potentially nullable type parameter.
+**DON'T** use `null` check on a potentially nullable type parameter.
 
-Given a generic type parameter `T` which has a nullable bound (e.g. the default
-bound of `Object?`), it is very easy to introduce erroneous null checks when
+Given a generic type parameter `T` which has a nullable bound (e.g., the default
+bound of `Object?`), it is very easy to introduce erroneous `null` checks when
 working with a variable of type `T?`. Specifically, it is not uncommon to have
 `T? x;` and want to assert that `x` has been set to a valid value of type `T`.
 A common mistake is to do so using `x!`. This is almost always incorrect, since
@@ -26,7 +27,7 @@ if `T` is a nullable type, `x` may validly hold `null` as a value of type `T`.
 ```dart
 T run<T>(T callback()) {
   T? result;
-   (() { result = callback(); })();
+  (() { result = callback(); })();
   return result!;
 }
 ```
@@ -35,7 +36,7 @@ T run<T>(T callback()) {
 ```dart
 T run<T>(T callback()) {
   T? result;
-   (() { result = callback(); })();
+  (() { result = callback(); })();
   return result as T;
 }
 ```

pkg/linter/lib/src/rules/prefer_conditional_assignment.dart

@@ -10,10 +10,10 @@ import '../analyzer.dart';
 import '../extensions.dart';
 import '../util/dart_type_utilities.dart' as type_utils;
 
-const _desc = r'Prefer using `??=` over testing for null.';
+const _desc = r'Prefer using `??=` over testing for `null`.';
 
 const _details = r'''
-**PREFER** using `??=` over testing for null.
+**PREFER** using `??=` over testing for `null`.
 
 As Dart has the `??=` operator, it is advisable to use it where applicable to
 improve the brevity of your code.

pkg/linter/lib/src/rules/prefer_const_constructors.dart

@@ -11,7 +11,7 @@ import 'package:analyzer/src/lint/linter.dart'; // ignore: implementation_import
 import '../analyzer.dart';
 import '../extensions.dart';
 
-const _desc = r'Prefer const with constant constructors.';
+const _desc = r'Prefer `const` with constant constructors.';
 
 const _details = r'''
 **PREFER** using `const` for instantiating constant constructors.

pkg/linter/lib/src/rules/prefer_const_constructors_in_immutables.dart

@@ -10,13 +10,13 @@ import 'package:collection/collection.dart' show IterableExtension;
 
 import '../analyzer.dart';
 
-const _desc = r'Prefer declaring const constructors on `@immutable` classes.';
+const _desc = r'Prefer declaring `const` constructors on `@immutable` classes.';
 
 const _details = r'''
-**PREFER** declaring const constructors on `@immutable` classes.
+**PREFER** declaring `const` constructors on `@immutable` classes.
 
 If a class is immutable, it is usually a good idea to make its constructor a
-const constructor.
+`const` constructor.
 
 **BAD:**
 ```dart

pkg/linter/lib/src/rules/prefer_const_declarations.dart

@@ -9,13 +9,13 @@ import 'package:analyzer/dart/ast/visitor.dart';
 import '../analyzer.dart';
 import '../ast.dart';
 
-const _desc = r'Prefer const over final for declarations.';
+const _desc = r'Prefer `const` over `final` for declarations.';
 
 const _details = r'''
-**PREFER** using `const` for const declarations.
+**PREFER** using `const` for constant-valued declarations.
 
-Const declarations are more hot-reload friendly and allow to use const
-constructors if an instantiation references this declaration.
+Constant declarations are more hot-reload friendly and allows
+the value to be used in other constant expressions.
 
 **BAD:**
 ```dart

pkg/linter/lib/src/rules/prefer_final_fields.dart

@@ -10,13 +10,13 @@ import 'package:analyzer/dart/element/element.dart';
 import '../analyzer.dart';
 import '../extensions.dart';
 
-const _desc = r'Private field could be final.';
+const _desc = r'Private field could be `final`.';
 
 const _details = r'''
-**DO** prefer declaring private fields as final if they are not reassigned later
-in the library.
+**DO** prefer declaring private fields as `final` if they are not reassigned
+later in the library.
 
-Declaring fields as final when possible is a good practice because it helps
+Declaring fields as `final` when possible is a good practice because it helps
 avoid accidental reassignments and allows the compiler to do optimizations.
 
 **BAD:**

pkg/linter/lib/src/rules/prefer_for_elements_to_map_fromIterable.dart

@@ -8,10 +8,10 @@ import 'package:analyzer/dart/ast/visitor.dart';
 
 import '../analyzer.dart';
 
-const _desc = r"Prefer 'for' elements when building maps from iterables.";
+const _desc = r'Prefer `for` elements when building maps from iterables.';
 
 const _details = r'''
-When building maps from iterables, it is preferable to use 'for' elements.
+When building maps from iterables, it is preferable to use `for` elements.
 
 Using 'for' elements brings several benefits including: