refactor: cleanup rules documentation (#550)

* refactor: remove unused PatternDocumentation

* refactor: remove unused RuleDocumentation

* chore: update changelog

* chore: add some tests

Author: dkrutskikh

CHANGELOG.md

@@ -3,7 +3,7 @@
 ## Unreleased
 
 * feat: introduce file metrics
-* refactor: cleanup anti-patterns, metrics documentation
+* refactor: cleanup anti-patterns, metrics and rules documentation
 
 ## 4.6.0
 

lib/src/analyzers/lint_analyzer/anti_patterns/anti_patterns_list/long_method.dart

@@ -17,7 +17,6 @@ import '../../models/scoped_function_declaration.dart';
 import '../../models/severity.dart';
 import '../../rules/flutter_rule_utils.dart';
 import '../models/pattern.dart';
-import '../models/pattern_documentation.dart';
 import '../pattern_utils.dart';
 
 class LongMethod extends Pattern {
@@ -37,10 +36,7 @@ class LongMethod extends Pattern {
         ),
         super(
           id: patternId,
-          documentation: const PatternDocumentation(
-            name: 'Long Method',
-            supportedType: EntityType.methodEntity,
-          ),
+          supportedType: EntityType.methodEntity,
           severity: readSeverity(patternSettings, Severity.none),
         );
 

lib/src/analyzers/lint_analyzer/anti_patterns/anti_patterns_list/long_parameter_list.dart

@@ -14,7 +14,6 @@ import '../../models/scoped_class_declaration.dart';
 import '../../models/scoped_function_declaration.dart';
 import '../../models/severity.dart';
 import '../models/pattern.dart';
-import '../models/pattern_documentation.dart';
 import '../pattern_utils.dart';
 
 class LongParameterList extends Pattern {
@@ -35,10 +34,7 @@ class LongParameterList extends Pattern {
         ),
         super(
           id: patternId,
-          documentation: const PatternDocumentation(
-            name: 'Long Parameter List',
-            supportedType: EntityType.methodEntity,
-          ),
+          supportedType: EntityType.methodEntity,
           severity: readSeverity(patternSettings, Severity.none),
         );
 

lib/src/analyzers/lint_analyzer/anti_patterns/models/pattern.dart

@@ -1,10 +1,10 @@
+import '../../models/entity_type.dart';
 import '../../models/internal_resolved_unit_result.dart';
 import '../../models/issue.dart';
 import '../../models/report.dart';
 import '../../models/scoped_class_declaration.dart';
 import '../../models/scoped_function_declaration.dart';
 import '../../models/severity.dart';
-import 'pattern_documentation.dart';
 
 /// An interface to communicate with a patterns
 ///
@@ -13,8 +13,8 @@ abstract class Pattern {
   /// The id of the pattern.
   final String id;
 
-  /// The documentation associated with the pattern.
-  final PatternDocumentation documentation;
+  /// The type of entities which will be analyzed by the pattern.
+  final EntityType supportedType;
 
   /// The severity of issues emitted by the pattern.
   final Severity severity;
@@ -24,7 +24,7 @@ abstract class Pattern {
 
   const Pattern({
     required this.id,
-    required this.documentation,
+    required this.supportedType,
     required this.severity,
   });
 

lib/src/analyzers/lint_analyzer/anti_patterns/models/pattern_documentation.dart

@@ -1,19 +1,16 @@
 import '../../models/severity.dart';
 import 'rule.dart';
-import 'rule_documentation.dart';
 import 'rule_type.dart';
 
 /// Represents a base class for angular-specific rules.
 abstract class AngularRule extends Rule {
   const AngularRule({
     required String id,
-    required RuleDocumentation documentation,
     required Severity severity,
     required Iterable<String> excludes,
   }) : super(
           id: id,
           type: RuleType.angular,
-          documentation: documentation,
           severity: severity,
           excludes: excludes,
         );

lib/src/analyzers/lint_analyzer/rules/models/angular_rule.dart

@@ -1,19 +1,16 @@
 import '../../models/severity.dart';
 import 'rule.dart';
-import 'rule_documentation.dart';
 import 'rule_type.dart';
 
 /// Represents a base class for common rules.
 abstract class CommonRule extends Rule {
   const CommonRule({
     required String id,
-    required RuleDocumentation documentation,
     required Severity severity,
     required Iterable<String> excludes,
   }) : super(
           id: id,
           type: RuleType.common,
-          documentation: documentation,
           severity: severity,
           excludes: excludes,
         );

lib/src/analyzers/lint_analyzer/rules/models/common_rule.dart

@@ -1,19 +1,16 @@
 import '../../models/severity.dart';
 import 'rule.dart';
-import 'rule_documentation.dart';
 import 'rule_type.dart';
 
 /// Represents a base class for Flutter-specific rules.
 abstract class FlutterRule extends Rule {
   const FlutterRule({
     required String id,
-    required RuleDocumentation documentation,
     required Severity severity,
     required Iterable<String> excludes,
   }) : super(
           id: id,
           type: RuleType.flutter,
-          documentation: documentation,
           severity: severity,
           excludes: excludes,
         );

lib/src/analyzers/lint_analyzer/rules/models/flutter_rule.dart

@@ -1,19 +1,16 @@
 import '../../models/severity.dart';
 import 'rule.dart';
-import 'rule_documentation.dart';
 import 'rule_type.dart';
 
 /// Represents a base class for intl-specific rules.
 abstract class IntlRule extends Rule {
   const IntlRule({
     required String id,
-    required RuleDocumentation documentation,
     required Severity severity,
     required Iterable<String> excludes,
   }) : super(
           id: id,
           type: RuleType.intl,
-          documentation: documentation,
           severity: severity,
           excludes: excludes,
         );

lib/src/analyzers/lint_analyzer/rules/models/intl_rule.dart

@@ -1,7 +1,6 @@
 import '../../models/internal_resolved_unit_result.dart';
 import '../../models/issue.dart';
 import '../../models/severity.dart';
-import 'rule_documentation.dart';
 import 'rule_type.dart';
 
 /// An interface to communicate with a rules
@@ -14,9 +13,6 @@ abstract class Rule {
   /// The type of the rule.
   final RuleType type;
 
-  /// The documentation associated with the rule
-  final RuleDocumentation documentation;
-
   /// The severity of issues emitted by the rule
   final Severity severity;
 
@@ -27,7 +23,6 @@ abstract class Rule {
   const Rule({
     required this.id,
     required this.type,
-    required this.documentation,
     required this.severity,
     required this.excludes,
   });

lib/src/analyzers/lint_analyzer/rules/models/rule.dart

@@ -13,7 +13,6 @@ import '../../../models/issue.dart';
 import '../../../models/severity.dart';
 import '../../flutter_rule_utils.dart';
 import '../../models/flutter_rule.dart';
-import '../../models/rule_documentation.dart';
 import '../../rule_utils.dart';
 
 part 'visitor.dart';
@@ -27,10 +26,6 @@ class AlwaysRemoveListenerRule extends FlutterRule {
   AlwaysRemoveListenerRule([Map<String, Object> config = const {}])
       : super(
           id: ruleId,
-          documentation: const RuleDocumentation(
-            name: 'Always remove listener',
-            brief: 'Warns when an event listener is added but never removed.',
-          ),
           severity: readSeverity(config, Severity.warning),
           excludes: readExcludes(config),
         );

lib/src/analyzers/lint_analyzer/rules/models/rule_documentation.dart

@@ -11,7 +11,6 @@ import '../../../models/internal_resolved_unit_result.dart';
 import '../../../models/issue.dart';
 import '../../../models/severity.dart';
 import '../../models/common_rule.dart';
-import '../../models/rule_documentation.dart';
 import '../../rule_utils.dart';
 
 part 'visitor.dart';
@@ -24,11 +23,6 @@ class AvoidIgnoringReturnValuesRule extends CommonRule {
   AvoidIgnoringReturnValuesRule([Map<String, Object> config = const {}])
       : super(
           id: ruleId,
-          documentation: const RuleDocumentation(
-            name: 'Avoid ignoring return values.',
-            brief:
-                'Warns when a return value of a method or function invocation or a class instance property access is not used.',
-          ),
           severity: readSeverity(config, Severity.warning),
           excludes: readExcludes(config),
         );

lib/src/analyzers/lint_analyzer/rules/rules_list/always_remove_listener/always_remove_listener.dart

@@ -9,7 +9,6 @@ import '../../../models/internal_resolved_unit_result.dart';
 import '../../../models/issue.dart';
 import '../../../models/severity.dart';
 import '../../models/common_rule.dart';
-import '../../models/rule_documentation.dart';
 import '../../rule_utils.dart';
 
 part 'visitor.dart';
@@ -22,11 +21,6 @@ class AvoidLateKeywordRule extends CommonRule {
   AvoidLateKeywordRule([Map<String, Object> config = const {}])
       : super(
           id: ruleId,
-          documentation: const RuleDocumentation(
-            name: "Avoid 'late' keyword",
-            brief:
-                'Warns when a field or variable is declared with a `late` keyword.',
-          ),
           severity: readSeverity(config, Severity.warning),
           excludes: readExcludes(config),
         );

lib/src/analyzers/lint_analyzer/rules/rules_list/avoid_ignoring_return_values/avoid_ignoring_return_values.dart

@@ -9,7 +9,6 @@ import '../../../models/internal_resolved_unit_result.dart';
 import '../../../models/issue.dart';
 import '../../../models/severity.dart';
 import '../../models/common_rule.dart';
-import '../../models/rule_documentation.dart';
 import '../../rule_utils.dart';
 
 part 'config_parser.dart';
@@ -26,10 +25,6 @@ class AvoidNestedConditionalExpressionsRule extends CommonRule {
       : _acceptableLevel = _ConfigParser.parseAcceptableLevel(config),
         super(
           id: ruleId,
-          documentation: const RuleDocumentation(
-            name: 'Avoid nested conditional expressions',
-            brief: 'Warns about nested conditional expressions.',
-          ),
           severity: readSeverity(config, Severity.style),
           excludes: readExcludes(config),
         );

lib/src/analyzers/lint_analyzer/rules/rules_list/avoid_late_keyword/avoid_late_keyword.dart

@@ -10,7 +10,6 @@ import '../../../models/internal_resolved_unit_result.dart';
 import '../../../models/issue.dart';
 import '../../../models/severity.dart';
 import '../../models/common_rule.dart';
-import '../../models/rule_documentation.dart';
 import '../../rule_utils.dart';
 
 part 'visitor.dart';
@@ -23,11 +22,6 @@ class AvoidNonNullAssertionRule extends CommonRule {
   AvoidNonNullAssertionRule([Map<String, Object> config = const {}])
       : super(
           id: ruleId,
-          documentation: const RuleDocumentation(
-            name: 'Avoid non null assertion',
-            brief:
-                'Warns when non null assertion operator (or “bang” operator) is used for a property access or method invocation. The operator check works at runtime and it may fail and throw a runtime exception.',
-          ),
           severity: readSeverity(config, Severity.warning),
           excludes: readExcludes(config),
         );

lib/src/analyzers/lint_analyzer/rules/rules_list/avoid_nested_conditional_expressions/avoid_nested_conditional_expressions.dart

@@ -11,7 +11,6 @@ import '../../../models/internal_resolved_unit_result.dart';
 import '../../../models/issue.dart';
 import '../../../models/severity.dart';
 import '../../models/angular_rule.dart';
-import '../../models/rule_documentation.dart';
 import '../../rule_utils.dart';
 
 part 'visitor.dart';
@@ -24,11 +23,6 @@ class AvoidPreserveWhitespaceFalseRule extends AngularRule {
   AvoidPreserveWhitespaceFalseRule([Map<String, Object> config = const {}])
       : super(
           id: ruleId,
-          documentation: const RuleDocumentation(
-            name: 'Avoid preserve whitespace false',
-            brief:
-                'Warns when a @Component annotation has explicit false value for preserveWhitespace.',
-          ),
           severity: readSeverity(config, Severity.warning),
           excludes: readExcludes(config),
         );

lib/src/analyzers/lint_analyzer/rules/rules_list/avoid_non_null_assertion/avoid_non_null_assertion.dart

@@ -11,7 +11,6 @@ import '../../../models/issue.dart';
 import '../../../models/severity.dart';
 import '../../flutter_rule_utils.dart';
 import '../../models/flutter_rule.dart';
-import '../../models/rule_documentation.dart';
 import '../../rule_utils.dart';
 
 part 'config_parser.dart';
@@ -34,11 +33,6 @@ class AvoidReturningWidgetsRule extends FlutterRule {
         _ignoredAnnotations = _ConfigParser.getIgnoredAnnotations(config),
         super(
           id: ruleId,
-          documentation: const RuleDocumentation(
-            name: 'Avoid returning widgets',
-            brief:
-                'Warns when a method or function returns a Widget or subclass of a Widget.',
-          ),
           severity: readSeverity(config, Severity.warning),
           excludes: readExcludes(config),
         );

lib/src/analyzers/lint_analyzer/rules/rules_list/avoid_preserve_whitespace_false/avoid_preserve_whitespace_false.dart

@@ -10,7 +10,6 @@ import '../../../models/issue.dart';
 import '../../../models/severity.dart';
 import '../../flutter_rule_utils.dart';
 import '../../models/flutter_rule.dart';
-import '../../models/rule_documentation.dart';
 import '../../rule_utils.dart';
 
 part 'visitor.dart';
@@ -26,11 +25,6 @@ class AvoidUnnecessarySetStateRule extends FlutterRule {
   AvoidUnnecessarySetStateRule([Map<String, Object> config = const {}])
       : super(
           id: ruleId,
-          documentation: const RuleDocumentation(
-            name: 'Avoid returning widgets',
-            brief:
-                'Warns when `setState` is called inside `initState`, `didUpdateWidget` or `build` methods and when it is called from a `sync` method that is called inside those methods.',
-          ),
           severity: readSeverity(config, Severity.warning),
           excludes: readExcludes(config),
         );