Simplify linter rule include and fix styling

Author: parlough

src/_includes/linter-rule-mention.md

@@ -1,6 +1,6 @@
-{:.linter-rule}
-{% if rule %}
-Linter rule: [{{rule}}](/tools/linter-rules/{{rule}})
-{% else %}
-Linter rules: [{{rule1}}](/tools/linter-rules/{{rule1}}), [{{rule2}}](/tools/linter-rules/{{rule2}})
-{% endif %}
+{%- assign split_rules = rules | split: ', ' -%}
+Linter rule{% if split_rules.size > 1 %}s{% endif %}:
+{%- for rule in split_rules %}
+  [{{rule}}](/tools/linter-rules/{{rule}}){%- unless forloop.last %}, {% endunless %}
+{%- endfor %}
+{:.linter-rule}

src/content/effective-dart/design.md

@@ -340,7 +340,7 @@ previous guidelines state, either:
 
 ### PREFER naming a method `to___()` if it copies the object's state to a new object
 
-{% include 'linter-rule-mention.md', rule:'use_to_and_as_if_applicable' %}
+{% include 'linter-rule-mention.md', rules:'use_to_and_as_if_applicable' %}
 
 A *conversion* method is one that returns a new object containing a copy of
 almost all of the state of the receiver but usually in some different form or
@@ -358,7 +358,7 @@ dateTime.toLocal();
 
 ### PREFER naming a method `as___()` if it returns a different representation backed by the original object
 
-{% include 'linter-rule-mention.md', rule:'use_to_and_as_if_applicable' %}
+{% include 'linter-rule-mention.md', rules:'use_to_and_as_if_applicable' %}
 
 Conversion methods are "snapshots". The resulting object has its own copy of the
 original object's state. There are other conversion-like methods that return
@@ -520,7 +520,7 @@ you can in a procedural or functional language.
 
 ### AVOID defining a one-member abstract class when a simple function will do
 
-{% include 'linter-rule-mention.md', rule:'one_member_abstracts' %}
+{% include 'linter-rule-mention.md', rules:'one_member_abstracts' %}
 
 Unlike Java, Dart has first-class functions, closures, and a nice light syntax
 for using them. If all you need is something like a callback, just use a
@@ -543,7 +543,7 @@ abstract class Predicate<E> {
 
 ### AVOID defining a class that contains only static members
 
-{% include 'linter-rule-mention.md', rule:'avoid_classes_with_only_static_members' %}
+{% include 'linter-rule-mention.md', rules:'avoid_classes_with_only_static_members' %}
 
 In Java and C#, every definition *must* be inside a class, so it's common to see
 "classes" that exist only as a place to stuff static members. Other classes are
@@ -656,7 +656,7 @@ comment.
 <a id="avoid-mixing-in-a-class-that-isnt-intended-to-be-a-mixin"></a>
 ### PREFER defining a pure `mixin` or pure `class` to a `mixin class`
 
-{% include 'linter-rule-mention.md', rule:'prefer_mixin' %}
+{% include 'linter-rule-mention.md', rules:'prefer_mixin' %}
 
 Dart previously (language version [2.12](/guides/language/evolution#dart-2-12)
 to [2.19](/guides/language/evolution#dart-2-19)) allowed any class that
@@ -708,7 +708,7 @@ A member belongs to an object and can be either methods or instance variables.
 
 ### PREFER making fields and top-level variables `final`
 
-{% include 'linter-rule-mention.md', rule:'prefer_final_fields' %}
+{% include 'linter-rule-mention.md', rules:'prefer_final_fields' %}
 
 State that is not *mutable*—that does not change over time—is
 easier for programmers to reason about. Classes and libraries that minimize the
@@ -821,7 +821,7 @@ dataSet.minimumValue;
 
 ### DO use setters for operations that conceptually change properties
 
-{% include 'linter-rule-mention.md', rule:'use_setters_to_change_properties' %}
+{% include 'linter-rule-mention.md', rules:'use_setters_to_change_properties' %}
 
 Deciding between a setter versus a method is similar to deciding between a
 getter versus a method. In both cases, the operation should be "field-like".
@@ -847,7 +847,7 @@ button.visible = false;
 
 ### DON'T define a setter without a corresponding getter
 
-{% include 'linter-rule-mention.md', rule:'avoid_setters_without_getters' %}
+{% include 'linter-rule-mention.md', rules:'avoid_setters_without_getters' %}
 
 Users think of getters and setters as visible properties of an object. A
 "dropbox" property that can be written to but not seen is confusing and
@@ -925,7 +925,7 @@ empty container, it might make sense to use a nullable type.
 
 ### AVOID returning `this` from methods just to enable a fluent interface
 
-{% include 'linter-rule-mention.md', rule:'avoid_returning_this' %}
+{% include 'linter-rule-mention.md', rules:'avoid_returning_this' %}
 
 Method cascades are a better solution for chaining method calls.
 
@@ -1049,7 +1049,7 @@ various cases, but the rough summary is:
 
 ### DO type annotate variables without initializers
 
-{% include 'linter-rule-mention.md', rule:'prefer_typing_uninitialized_variables' %}
+{% include 'linter-rule-mention.md', rules:'prefer_typing_uninitialized_variables' %}
 
 The type of a variable—top-level, local, static field, or instance
 field—can often be inferred from its initializer. However, if there is no
@@ -1078,7 +1078,7 @@ if (node is Constructor) {
 
 ### DO type annotate fields and top-level variables if the type isn't obvious
 
-{% include 'linter-rule-mention.md', rule:'type_annotate_public_apis' %}
+{% include 'linter-rule-mention.md', rules:'type_annotate_public_apis' %}
 
 Type annotations are important documentation for how a library should be used.
 They form boundaries between regions of a program to isolate the source of a
@@ -1130,7 +1130,7 @@ annotations on APIs help *users* of your code, types on private members help
 
 ### DON'T redundantly type annotate initialized local variables
 
-{% include 'linter-rule-mention.md', rule:'omit_local_variable_types' %}
+{% include 'linter-rule-mention.md', rules:'omit_local_variable_types' %}
 
 Local variables, especially in modern code where functions tend to be small,
 have very little scope. Omitting the type focuses the reader's attention on the
@@ -1237,7 +1237,7 @@ different type annotation conventions, as described in the next two guidelines.
 
 ### DON'T annotate inferred parameter types on function expressions
 
-{% include 'linter-rule-mention.md', rule:'avoid_types_on_closure_parameters' %}
+{% include 'linter-rule-mention.md', rules:'avoid_types_on_closure_parameters' %}
 
 Anonymous functions are almost always immediately passed to a method taking a
 callback of some type.
@@ -1268,7 +1268,7 @@ function's parameters. In those cases, you may need to annotate.
 
 ### DON'T type annotate initializing formals
 
-{% include 'linter-rule-mention.md', rule:'type_init_formals' %}
+{% include 'linter-rule-mention.md', rules:'type_init_formals' %}
 
 If a constructor parameter is using `this.` to initialize a field, 
 or `super.` to forward a super parameter, 
@@ -1511,7 +1511,7 @@ void handleError([!void Function()!] operation, [!Function!] errorHandler) {
 
 ### DON'T specify a return type for a setter
 
-{% include 'linter-rule-mention.md', rule:'avoid_return_types_on_setters' %}
+{% include 'linter-rule-mention.md', rules:'avoid_return_types_on_setters' %}
 
 Setters always return `void` in Dart. Writing the word is pointless.
 
@@ -1528,7 +1528,7 @@ set foo(Foo value) { ... }
 
 ### DON'T use the legacy typedef syntax
 
-{% include 'linter-rule-mention.md', rule:'prefer_generic_function_type_aliases' %}
+{% include 'linter-rule-mention.md', rules:'prefer_generic_function_type_aliases' %}
 
 Dart has two notations for defining a named typedef for a function type. The
 original syntax looks like:
@@ -1586,7 +1586,7 @@ it's deprecated.
 
 ### PREFER inline function types over typedefs
 
-{% include 'linter-rule-mention.md', rule:'avoid_private_typedef_functions' %}
+{% include 'linter-rule-mention.md', rules'avoid_private_typedef_functions' %}
 
 In Dart, if you want to use a function type for a field, variable, or
 generic type argument, you can define a typedef for the function type.
@@ -1623,7 +1623,7 @@ that clarity.
 
 ### PREFER using function type syntax for parameters
 
-{% include 'linter-rule-mention.md', rule:'use_function_type_syntax_for_parameters' %}
+{% include 'linter-rule-mention.md', rules:'use_function_type_syntax_for_parameters' %}
 
 Dart has a special syntax when defining a parameter whose type is a function.
 Sort of like in C, you surround the parameter's name with the function's return
@@ -1758,7 +1758,7 @@ In Dart, optional parameters can be either positional or named, but not both.
 
 ### AVOID positional boolean parameters
 
-{% include 'linter-rule-mention.md', rule:'avoid_positional_boolean_parameters' %}
+{% include 'linter-rule-mention.md', rules:'avoid_positional_boolean_parameters' %}
 
 Unlike other types, booleans are usually used in literal form. Values like
 numbers are usually wrapped in named constants, but we typically pass around
@@ -1872,7 +1872,7 @@ elements to follow.
 
 ### DO override `hashCode` if you override `==`
 
-{% include 'linter-rule-mention.md', rule:'hash_and_equals' %}
+{% include 'linter-rule-mention.md', rules:'hash_and_equals' %}
 
 The default hash code implementation provides an *identity* hash—two
 objects generally only have the same hash code if they are the exact same
@@ -1900,7 +1900,7 @@ you're trying to express.
 
 ### AVOID defining custom equality for mutable classes
 
-{% include 'linter-rule-mention.md', rule:'avoid_equals_and_hash_code_on_mutable_classes' %}
+{% include 'linter-rule-mention.md', rules:'avoid_equals_and_hash_code_on_mutable_classes' %}
 
 When you define `==`, you also have to define `hashCode`. Both of those should
 take into account the object's fields. If those fields *change* then that
@@ -1912,7 +1912,7 @@ true.
 
 ### DON'T make the parameter to `==` nullable
 
-{% include 'linter-rule-mention.md', rule:'avoid_null_checks_in_equality_operators' %}
+{% include 'linter-rule-mention.md', rules:'avoid_null_checks_in_equality_operators' %}
 
 The language specifies that `null` is equal only to itself, and that the `==`
 method is called only if the right-hand side is not `null`.

src/content/effective-dart/documentation.md

@@ -72,7 +72,7 @@ and uses the special `///` syntax that `dart doc` looks for.
 
 ### DO use `///` doc comments to document members and types
 
-{% include 'linter-rule-mention.md', rule:'slash_for_doc_comments' %}
+{% include 'linter-rule-mention.md', rules:'slash_for_doc_comments' %}
 
 Using a doc comment instead of a regular comment enables 
 [`dart doc`][] to find it
@@ -101,7 +101,7 @@ up.
 
 ### PREFER writing doc comments for public APIs
 
-{% include 'linter-rule-mention.md', rule1:'package_api_docs', rule2:'public_member_api_docs' %}
+{% include 'linter-rule-mention.md', rules:'package_api_docs, public_member_api_docs' %}
 
 You don't have to document every single library, top-level variable, type, and
 member, but you should document most of them.
@@ -342,7 +342,7 @@ makes an API easier to learn.
 
 ### DO use square brackets in doc comments to refer to in-scope identifiers
 
-{% include 'linter-rule-mention.md', rule:'comment_references' %}
+{% include 'linter-rule-mention.md', rules:'comment_references' %}
 
 If you surround things like variable, method, or type names in square brackets,
 then `dart doc` looks up the name and links to the relevant API docs.

src/content/effective-dart/index.md

@@ -105,7 +105,7 @@ that can help you follow a guideline
 then the guideline links to those rules.
 The links use the following format:
 
-{% include 'linter-rule-mention.md', rule:'unnecessary_getters_setters' %}
+{% include 'linter-rule-mention.md', rules:'unnecessary_getters_setters' %}
 
 To learn how to use the linter,
 see [Enabling linter rules][]

src/content/effective-dart/style.md

@@ -35,7 +35,7 @@ Identifiers come in three flavors in Dart.
 
 ### DO name types using `UpperCamelCase`
 
-{% include 'linter-rule-mention.md', rule:'camel_case_types' %}
+{% include 'linter-rule-mention.md', rules:'camel_case_types' %}
 
 Classes, enum types, typedefs, and type parameters should capitalize the first
 letter of each word (including the first word), and use no separators.
@@ -77,7 +77,7 @@ class C { ... }
 
 ### DO name extensions using `UpperCamelCase`
 
-{% include 'linter-rule-mention.md', rule:'camel_case_extensions' %}
+{% include 'linter-rule-mention.md', rules:'camel_case_extensions' %}
 
 Like types, [extensions][] should capitalize the first letter of each word
 (including the first word),
@@ -95,7 +95,7 @@ extension SmartIterable<T> on Iterable<T> { ... }
 <a id="do-name-libraries-and-source-files-using-lowercase_with_underscores"></a>
 ### DO name packages, directories, and source files using `lowercase_with_underscores` {:#do-name-packages-and-file-system-entities-using-lowercase-with-underscores}
 
-{% include 'linter-rule-mention.md', rule1:'file_names', rule2:'package_names' %}
+{% include 'linter-rule-mention.md', rules:'file_names, package_names' %}
 
 Some file systems are not case-sensitive, so many projects require filenames to
 be all lowercase. Using a separating character allows names to still be readable
@@ -120,7 +120,7 @@ mypackage
 
 ### DO name import prefixes using `lowercase_with_underscores`
 
-{% include 'linter-rule-mention.md', rule:'library_prefixes' %}
+{% include 'linter-rule-mention.md', rules:'library_prefixes' %}
 
 <?code-excerpt "style_lib_good.dart (import-as)" replace="/(package):examples\/effective_dart\/foo.dart[^']*/$1:angular_components\/angular_components.dart/g; /(package):examples\/effective_dart\/bar.dart[^']*/$1:js\/js.dart/g"?>
 ```dart tag=good
@@ -139,7 +139,7 @@ import 'package:js/js.dart' as JS;
 
 ### DO name other identifiers using `lowerCamelCase`
 
-{% include 'linter-rule-mention.md', rule:'non_constant_identifier_names' %}
+{% include 'linter-rule-mention.md', rules:'non_constant_identifier_names' %}
 
 Class members, top-level definitions, variables, parameters, and named
 parameters should capitalize the first letter of each word *except* the first
@@ -159,7 +159,7 @@ void align(bool clearItems) {
 
 ### PREFER using `lowerCamelCase` for constant names
 
-{% include 'linter-rule-mention.md', rule:'constant_identifier_names' %}
+{% include 'linter-rule-mention.md', rules:'constant_identifier_names' %}
 
 In new code, use `lowerCamelCase` for constant variables, including enum values.
 
@@ -330,7 +330,7 @@ A single linter rule handles all the ordering guidelines:
 
 ### DO place `dart:` imports before other imports
 
-{% include 'linter-rule-mention.md', rule:'directives_ordering' %}
+{% include 'linter-rule-mention.md', rules:'directives_ordering' %}
 
 <?code-excerpt "style_lib_good.dart (dart-import-first)" replace="/\w+\/effective_dart\///g"?>
 ```dart tag=good
@@ -344,7 +344,7 @@ import 'package:foo/foo.dart';
 
 ### DO place `package:` imports before relative imports
 
-{% include 'linter-rule-mention.md', rule:'directives_ordering' %}
+{% include 'linter-rule-mention.md', rules:'directives_ordering' %}
 
 <?code-excerpt "style_lib_good.dart (pkg-import-before-local)" replace="/\w+\/effective_dart\///g;/'foo/'util/g"?>
 ```dart tag=good
@@ -357,7 +357,7 @@ import 'util.dart';
 
 ### DO specify exports in a separate section after all imports
 
-{% include 'linter-rule-mention.md', rule:'directives_ordering' %}
+{% include 'linter-rule-mention.md', rules:'directives_ordering' %}
 
 <?code-excerpt "style_lib_good.dart (export)"?>
 ```dart tag=good
@@ -377,7 +377,7 @@ import 'src/foo_bar.dart';
 
 ### DO sort sections alphabetically
 
-{% include 'linter-rule-mention.md', rule:'directives_ordering' %}
+{% include 'linter-rule-mention.md', rules:'directives_ordering' %}
 
 <?code-excerpt "style_lib_good.dart (sorted)" replace="/\w+\/effective_dart\///g"?>
 ```dart tag=good
@@ -436,7 +436,7 @@ to produce beautiful code.
 
 ### AVOID lines longer than 80 characters
 
-{% include 'linter-rule-mention.md', rule:'lines_longer_than_80_chars' %}
+{% include 'linter-rule-mention.md', rules:'lines_longer_than_80_chars' %}
 
 Readability studies show that long lines of text are harder to read because your
 eye has to travel farther when moving to the beginning of the next line. This is
@@ -463,7 +463,7 @@ shorter ones can alter the program.
 <a id="do-use-curly-braces-for-all-flow-control-structures"></a>
 ### DO use curly braces for all flow control statements
 
-{% include 'linter-rule-mention.md', rule:'curly_braces_in_flow_control_structures' %}
+{% include 'linter-rule-mention.md', rules:'curly_braces_in_flow_control_structures' %}
 
 Doing so avoids the [dangling else][] problem.