Update documentation for custom lints: add descriptions, examples (#102)

* Update avoid_using_api doc

* Update avoid-global-state doc

* Update avoid_late doc

* Update avoid_non_null_assertion docs

* Update avoid_returning_widget doc

* Update avoid_unnecessary_setstate doc

* Update avoid_unnecessary_type_assertions doc

* Add example to avoid_unused_parameters doc

* Update cyclomatic_complexity doc

* Update double_literal_format doc

* Update function_lines_of_code doc

* Update member_ordering doc

* Update newline_before_return doc

* Update no_empty_block doc

* Update no_equal_then_else doc

* Update no_magic_number doc

* Update number_of_parameters doc

* Update prefer_conditional_expressions doc

* Update prefer_first doc

* Update prefer_last doc

* Add example for prefer_match_file_name

* Update proper_super_calls doc

* Update README

* Add config examples to parametrised lints

* Update README

* typos

* consistent markdown headers for examples

* more header fixes

Author: yurii-prykhodko-solid

README.md

@@ -4,8 +4,37 @@ import 'package:custom_lint_builder/custom_lint_builder.dart';
 import 'package:solid_lints/models/rule_config.dart';
 import 'package:solid_lints/models/solid_lint_rule.dart';
 
-/// A global state rule which forbids using variables
-/// that can be globally modified.
+/// Avoid top-level and static mutable variables.
+///
+/// Top-level variables can be modified from anywhere,
+/// which leads to hard to debug applications.
+///
+/// Prefer using a state management solution.
+///
+/// ### Example
+///
+/// #### BAD:
+///
+/// ```dart
+/// var globalMutable = 0; // LINT
+///
+/// class Test {
+///   static int globalMutable = 0; // LINT
+/// }
+/// ```
+///
+///
+/// #### GOOD:
+///
+/// ```dart
+/// final globalFinal = 1;
+/// const globalConst = 1;
+///
+/// class Test {
+///   static const int globalConst = 1;
+///   static final int globalFinal = 1;
+/// }
+/// ```
 class AvoidGlobalStateRule extends SolidLintRule {
   /// The [LintCode] of this lint rule that represents
   /// the error whether we use global state.

lib/lints/avoid_global_state/avoid_global_state_rule.dart

@@ -6,7 +6,47 @@ import 'package:solid_lints/models/rule_config.dart';
 import 'package:solid_lints/models/solid_lint_rule.dart';
 import 'package:solid_lints/utils/types_utils.dart';
 
-/// A `late` keyword rule which forbids using it to avoid runtime exceptions.
+/// Avoid `late` keyword
+///
+/// Using `late` disables compile time safety for what would else be a nullable
+/// variable. Instead, a runtime check is made, which may throw an unexpected
+/// exception for an uninitialized variable.
+///
+/// ### Example config:
+///
+/// ```yaml
+/// custom_lint:
+///    rules:
+///      - avoid_late_keyword:
+///        allow_initialized: false
+///        ignored_types:
+///         - AnimationController
+///         - ColorTween
+/// ```
+///
+/// ### Example
+///
+/// #### BAD:
+/// ```dart
+/// class AvoidLateKeyword {
+///   late final int field; // LINT
+///
+///   void test() {
+///     late final local = ''; // LINT
+///   }
+/// }
+/// ```
+///
+/// #### GOOD:
+/// ```dart
+/// class AvoidLateKeyword {
+///   final int? field; // LINT
+///
+///   void test() {
+///     final local = ''; // LINT
+///   }
+/// }
+/// ```
 class AvoidLateKeywordRule extends SolidLintRule<AvoidLateKeywordParameters> {
   /// The [LintCode] of this lint rule that represents
   /// the error whether we use `late` keyword.

lib/lints/avoid_late_keyword/avoid_late_keyword_rule.dart

@@ -1,7 +1,7 @@
 /// A data model class that represents the "avoid late keyword" input
 /// parameters.
 class AvoidLateKeywordParameters {
-  /// Allow immediately initialised late variables.
+  /// Allow immediately initialized late variables.
   ///
   /// ```dart
   /// late var ok = 0; // ok when allowInitialized == true
@@ -10,6 +10,21 @@ class AvoidLateKeywordParameters {
   final bool allowInitialized;
 
   /// Types that would be ignored by avoid-late rule
+  ///
+  /// Example:
+  ///
+  /// ```yaml
+  /// custom_lint:
+  ///   rules:
+  ///     - avoid_late_keyword:
+  ///       ignored_types:
+  ///         - ColorTween
+  /// ```
+  ///
+  /// ```dart
+  /// late ColorTween tween; // OK
+  /// late int colorValue; // LINT
+  /// ```
   final Iterable<String> ignoredTypes;
 
   /// Constructor for [AvoidLateKeywordParameters] model

lib/lints/avoid_late_keyword/models/avoid_late_keyword_parameters.dart

@@ -6,8 +6,37 @@ import 'package:custom_lint_builder/custom_lint_builder.dart';
 import 'package:solid_lints/models/rule_config.dart';
 import 'package:solid_lints/models/solid_lint_rule.dart';
 
-/// Rule which forbids using bang operator ("!")
-/// as it may result in runtime exceptions.
+/// Rule which warns about usages of bang operator ("!")
+/// as it may result in unexpected runtime exceptions.
+///
+/// "Bang" operator with Maps is allowed, as [Dart docs](https://dart.dev/null-safety/understanding-null-safety#the-map-index-operator-is-nullable)
+/// recommend using it for accessing Map values that are known to be present.
+///
+/// ### Example
+/// #### BAD:
+///
+/// ```dart
+/// Object? object;
+/// int? number;
+///
+/// final int computed = 1 + number!; // LINT
+/// object!.method(); // LINT
+/// ```
+///
+/// #### GOOD:
+/// ```dart
+/// Object? object;
+/// int? number;
+///
+/// if (number != null) {
+///   final int computed = 1 + number;
+/// }
+/// object?.method();
+///
+/// // No lint on maps
+/// final map = {'key': 'value'};
+/// map['key']!;
+/// ```
 class AvoidNonNullAssertionRule extends SolidLintRule {
   /// The [LintCode] of this lint rule that represents
   /// the error whether we use bang operator.

lib/lints/avoid_non_null_assertion/avoid_non_null_assertion_rule.dart

@@ -5,7 +5,37 @@ import 'package:solid_lints/models/rule_config.dart';
 import 'package:solid_lints/models/solid_lint_rule.dart';
 import 'package:solid_lints/utils/types_utils.dart';
 
-/// A rule which forbids returning widgets from functions and methods.
+/// A rule which warns about returning widgets from functions and methods.
+///
+/// Using functions instead of Widget subclasses for decomposing Widget trees
+/// may cause unexpected behavior and performance issues.
+///
+/// More details: https://github.com/flutter/flutter/issues/19269
+///
+/// ### Example
+///
+/// #### BAD:
+///
+/// ```dart
+/// Widget avoidReturningWidgets() => const SizedBox(); // LINT
+///
+/// class MyWidget extends StatelessWidget {
+///   Widget _test1() => const SizedBox(); // LINT
+///   Widget get _test3 => const SizedBox(); // LINT
+/// }
+/// ```
+///
+///
+/// #### GOOD:
+///
+/// ```dart
+/// class MyWidget extends StatelessWidget {
+///   @override
+///   Widget build(BuildContext context) {
+///     return const SizedBox();
+///   }
+/// }
+/// ```
 class AvoidReturningWidgetsRule extends SolidLintRule {
   /// The [LintCode] of this lint rule that represents
   /// the error whether we return a widget.

lib/lints/avoid_returning_widgets/avoid_returning_widgets_rule.dart

@@ -21,11 +21,27 @@ import 'package:solid_lints/models/solid_lint_rule.dart';
 /// - async methods
 /// - callbacks
 ///
-/// Example:
+/// ### Example:
+/// #### BAD:
 /// ```dart
 /// void initState() {
 ///   setState(() => foo = 'bar');  // lint
 ///   changeState();                // lint
+/// }
+///
+/// void changeState() {
+///   setState(() => foo = 'bar');
+/// }
+///
+/// void triggerFetch() async {
+///   await fetch();
+///   if (mounted) setState(() => foo = 'bar');
+/// }
+/// ```
+///
+/// #### GOOD:
+/// ```dart
+/// void initState() {
 ///   triggerFetch();               // OK
 ///   stream.listen((event) => setState(() => foo = event)); // OK
 /// }

lib/lints/avoid_unnecessary_setstate/avoid_unnecessary_set_state_rule.dart

@@ -17,8 +17,29 @@ const operatorIsName = 'is';
 /// The name of 'whereType' method
 const whereTypeMethodName = 'whereType';
 
-/// An `avoid_unnecessary_type_assertions` rule which
-/// warns about unnecessary usage of `is` and `whereType` operators
+/// Warns about unnecessary usage of `is` and `whereType` operators.
+///
+/// ### Example:
+/// #### BAD:
+/// ```dart
+/// final testList = [1.0, 2.0, 3.0];
+/// final result = testList is List<double>; // LINT
+/// final negativeResult = testList is! List<double>; // LINT
+/// testList.whereType<double>(); // LINT
+///
+/// final double d = 2.0;
+/// final casted = d is double; // LINT
+/// ```
+///
+/// #### OK:
+/// ```dart
+/// final dynamicList = <dynamic>[1.0, 2.0];
+/// dynamicList.whereType<double>();
+///
+/// final double? nullableD = 2.0;
+/// // casting `Type? is Type` is allowed
+/// final castedD = nullableD is double;
+/// ```
 class AvoidUnnecessaryTypeAssertions extends SolidLintRule {
   /// The [LintCode] of this lint rule that represents
   /// the error whether we use bad formatted double literals.

lib/lints/avoid_unnecessary_type_assertions/avoid_unnecessary_type_assertions_rule.dart

@@ -4,8 +4,44 @@ import 'package:solid_lints/lints/avoid_unused_parameters/avoid_unused_parameter
 import 'package:solid_lints/models/rule_config.dart';
 import 'package:solid_lints/models/solid_lint_rule.dart';
 
-/// A `avoid_unused_parameters` rule which
-/// warns about unused parameters
+/// Warns about unused function, method, constructor or factory parameters.
+///
+/// ### Example:
+/// #### BAD:
+/// ```dart
+/// void fun(String x) {} // LINT
+/// void fun2(String x, String y) { // LINT
+///   print(y);
+/// }
+///
+/// class TestClass {
+///   static void staticMethod(int a) {} // LINT
+///   void method(String s) {} // LINT
+///
+///   TestClass([int a]); // LINT
+///   factory TestClass.named(int a) { // LINT
+///     return TestClass();
+///   }
+/// }
+/// ```
+///
+/// #### OK:
+/// ```dart
+/// void fun(String _) {} // Replacing with underscores silences the warning
+/// void fun2(String _, String y) {
+///   print(y);
+/// }
+///
+/// class TestClass {
+///   static void staticMethod(int _) {} // OK
+///   void method(String _) {} // OK
+///
+///   TestClass([int _]); // OK
+///   factory TestClass.named(int _) { // OK
+///     return TestClass();
+///   }
+/// }
+/// ```
 class AvoidUnusedParametersRule extends SolidLintRule {
   /// The [LintCode] of this lint rule that represents
   /// the error whether we use bad formatted double literals.

lib/lints/avoid_unused_parameters/avoid_unused_parameters_rule.dart

@@ -10,6 +10,57 @@ import 'package:solid_lints/utils/path_utils.dart';
 
 /// A `avoid_using_api` rule which
 /// warns about usage of avoided APIs
+///
+///
+/// ### Usage
+///
+/// External code can be "deprecated" when there is a better option available:
+///
+/// ```yaml
+/// custom_lint:
+///   rules:
+///     - avoid_using_api:
+///       severity: info
+///       entries:
+///         - class_name: Future
+///           identifier: wait
+///           source: dart:async
+///           reason: "Future.wait should be avoided because it loses type
+///                    safety for the results. Use a Record's `wait` method
+///                    instead."
+///           severity: warning
+/// ```
+///
+/// Result:
+///
+/// ```dart
+/// void main() async {
+///   await Future.wait([...]); // LINT
+///   await (...).wait; // OK
+/// }
+/// ```
+///
+/// ### Advanced Usage
+///
+/// Each entry also has `includes` and `excludes` parameters.
+/// These paths utilize [Glob](https://pub.dev/packages/glob)
+/// patterns to determine if a lint entry should be applied to a file.
+///
+/// For example, a lint to prevent usage of a domain-only package outside of the
+/// domain folder:
+///
+/// ```yaml
+/// custom_lint:
+///   rules:
+///     - avoid_using_api:
+///       severity: info
+///       entries:
+///         - source: package:domain_models
+///           excludes:
+///             - "**/domain/**.dart"
+///           reason: "domain_models is only intended to be used in the domain
+///                    layer."
+/// ```
 class AvoidUsingApiRule extends SolidLintRule<AvoidUsingApiParameters> {
   /// The [LintCode] of this lint rule that represents
   /// the error whether we use bad formatted double literals.