refactor: update automatic documentation generation

README.md

@@ -19,13 +19,16 @@ dev_dependencies:
   solid_lints: <INSERT LATEST VERSION>
 ```
 
-And then include `solid_lints` into your project top-level `analysis_options.yaml`:
+Enable the plugin and include `solid_lints` in your project's top-level `analysis_options.yaml`:
 
 ```yaml
 include: package:solid_lints/analysis_options.yaml
+
+plugins:
+  solid_lints:
 ```
 
-Also you can use a specialized rule set designed for Dart tests.
+Also, you can use a specialized rule set designed for Dart tests.
 Add an `analysis_options.yaml` file under the `test/` directory, and include the ruleset:
 
 ```yaml
@@ -36,7 +39,18 @@ Then you can see suggestions in your IDE or you can run checks manually:
 
 ```bash
 dart analyze;
-dart run custom_lint;
+```
+
+# Configuration
+
+You can customize individual rule settings in your `analysis_options.yaml` under the `solid_lints` configuration block:
+
+```yaml
+solid_lints:
+  diagnostics:
+    cyclomatic_complexity:
+      max_complexity: 10
+    avoid_non_null_assertion: true
 ```
 
 # Badge

doc/docusaurus/docs/1_rulesets/test.md

@@ -65,6 +65,12 @@ Given the quite large threshold configured for this metric we considered extract
 
 Both options didn't look right, so we decided that tests are ok to be long.
 
+## cyclomatic_complexity
+
+State: **Disabled**.
+
+Since we're not using the `function_lines_of_code` rule, the `main()` function in tests can have high cyclomatic complexity. For the rationale against splitting up `main()` in tests, see the comments for `function_lines_of_code` above.
+
 ## prefer_match_file_name
 
 State: **Disabled**.

doc/docusaurus/package.json

@@ -16,8 +16,8 @@
     "typecheck": "tsc"
   },
   "dependencies": {
-    "@docusaurus/core": "^3.1.0",
-    "@docusaurus/preset-classic": "^3.1.0",
+    "@docusaurus/core": "^3.10.1",
+    "@docusaurus/preset-classic": "^3.10.1",
     "@easyops-cn/docusaurus-search-local": "^0.40.1",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.1.0",

example/analysis_options.yaml

@@ -1,26 +1,25 @@
 include: package:solid_lints/analysis_options.yaml
 
-analyzer:
-  plugins:
-    - custom_lint
+plugins:
+  solid_lints:
 
-custom_lint:
-  rules:
-    - cyclomatic_complexity:
+solid_lints:
+  diagnostics:
+    cyclomatic_complexity:
       max_complexity: 4
-    - number_of_parameters:
+    number_of_parameters:
       max_parameters: 2
-    - function_lines_of_code:
+    function_lines_of_code:
       max_lines: 50
-    - avoid_non_null_assertion
-    - avoid_late_keyword
-    - avoid_global_state
-    - avoid_returning_widgets
-    - avoid_unnecessary_setstate
-    - double_literal_format
-    - avoid_unnecessary_type_assertions
-    - avoid_debug_print_in_release
-    - avoid_using_api:
+    avoid_non_null_assertion: true
+    avoid_late_keyword: true
+    avoid_global_state: true
+    avoid_returning_widgets: true
+    avoid_unnecessary_setstate: true
+    double_literal_format: true
+    avoid_unnecessary_type_assertions: true
+    avoid_debug_print_in_release: true
+    avoid_using_api:
       severity: info
       entries:
         - class_name: Future

example/pubspec.yaml

@@ -10,7 +10,6 @@ dependencies:
     sdk: flutter
 
 dev_dependencies:
-  custom_lint: ^0.8.1
   solid_lints:
     path: ../
   test: ^1.25.14

lib/analysis_options.yaml

@@ -1,6 +1,4 @@
 analyzer:
-  plugins:
-    - custom_lint
   exclude:
     # General generated files
     - "**/*.g.dart"

lib/src/common/parameters/excluded_annotations_list_parameter.dart

@@ -3,6 +3,8 @@ import 'package:analyzer/dart/ast/ast.dart';
 /// A parameter model representing excluded annotations for linting.
 /// It defines class-level annotations that indicate when class members
 /// should be ignored during analysis.
+///
+/// @docType String | List<String>
 class ExcludedAnnotationsListParameter {
   /// The set of excluded annotation names.
   final Set<String> excludedAnnotations;

lib/src/common/parameters/excluded_entities_list_parameter.dart

@@ -3,10 +3,11 @@ import 'package:analyzer/dart/ast/ast.dart';
 /// A model representing "exclude_entity" parameters for linting, defining
 /// identifiers (classes, mixins, enums, extensions) to be ignored during
 /// analysis.
-/// Supported entities:
 ///   - mixin
 ///   - extension
 ///   - enum
+///
+/// @docType String | List<String>
 class ExcludedEntitiesListParameter {
   /// The parameter model
   final Set<String> excludedEntityNames;

lib/src/common/parameters/excluded_identifiers_list_parameter.dart

@@ -4,6 +4,8 @@ import 'package:solid_lints/src/common/parameters/excluded_identifier_parameter.
 
 /// A model representing "exclude" parameters for linting, defining
 /// identifiers (classes, methods, functions) to be ignored during analysis.
+///
+/// @docType String | Map | List<String | Map>
 class ExcludedIdentifiersListParameter {
   /// A list of identifiers (classes, methods, functions) that should be
   /// excluded from the lint.

lib/src/lints/avoid_late_keyword/avoid_late_keyword_rule.dart

@@ -14,13 +14,14 @@ import 'package:solid_lints/src/models/solid_lint_rule.dart';
 /// ### Example config:
 ///
 /// ```yaml
-/// custom_lint:
-///    rules:
-///      - avoid_late_keyword:
-///        allow_initialized: false
-///        ignored_types:
-///         - AnimationController
-///         - ColorTween
+/// plugins:
+///   solid_lints:
+///     diagnostics:
+///       avoid_late_keyword:
+///         allow_initialized: false
+///         ignored_types:
+///           - AnimationController
+///           - ColorTween
 /// ```
 ///
 /// ### Example
@@ -47,17 +48,18 @@ import 'package:solid_lints/src/models/solid_lint_rule.dart';
 /// }
 /// ```
 class AvoidLateKeywordRule extends SolidLintRule<AvoidLateKeywordParameters> {
-  static const String _lintName = 'avoid_late_keyword';
+  /// The lint rule name. Must be public to generate docs.
+  static const String lintName = 'avoid_late_keyword';
 
   static const LintCode _code = LintCode(
-    _lintName,
+    lintName,
     'Avoid using the "late" keyword. It may result in runtime exceptions.',
   );
 
   /// Creates an instance of [AvoidLateKeywordRule].
   AvoidLateKeywordRule({required super.analysisOptionsLoader})
       : super.withParameters(
-          name: _lintName,
+          name: lintName,
           description: 'Warns against using the late keyword.',
           parametersParser: AvoidLateKeywordParameters.fromJson,
         );

lib/src/lints/avoid_late_keyword/models/avoid_late_keyword_parameters.dart

@@ -10,15 +10,15 @@ 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
+  /// plugins:
+  ///   solid_lints:
+  ///     diagnostics:
+  ///       avoid_late_keyword:
+  ///         ignored_types:
+  ///           - ColorTween
   /// ```
   ///
   /// ```dart
@@ -37,7 +37,8 @@ class AvoidLateKeywordParameters {
   factory AvoidLateKeywordParameters.fromJson(Map<String, Object?> json) =>
       AvoidLateKeywordParameters(
         allowInitialized: json['allow_initialized'] as bool? ?? false,
-        ignoredTypes:
-            List<String>.from(json['ignored_types'] as Iterable? ?? []),
+        ignoredTypes: List<String>.from(
+          json['ignored_types'] as Iterable? ?? [],
+        ),
       );
 }

lib/src/lints/avoid_non_null_assertion/avoid_non_null_assertion_rule.dart

@@ -11,6 +11,18 @@ import 'package:solid_lints/src/models/solid_lint_rule.dart';
 /// "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 config:
+///
+/// ```yaml
+/// plugins:
+///   solid_lints:
+///     diagnostics:
+///       avoid_non_null_assertion:
+///         ignored_types:
+///           - IMap
+///           - BuiltMap
+/// ```
+///
 /// ### Example
 /// #### BAD:
 ///

lib/src/lints/avoid_returning_widgets/avoid_returning_widgets_rule.dart

@@ -15,6 +15,18 @@ import 'package:solid_lints/src/models/solid_lint_rule.dart';
 ///
 /// More details: https://github.com/flutter/flutter/issues/19269
 ///
+/// ### Example config:
+///
+/// ```yaml
+/// plugins:
+///   solid_lints:
+///     diagnostics:
+///       avoid_returning_widgets:
+///         exclude:
+///           - class_name: MyWidget
+///             method_name: buildCustomButton
+/// ```
+///
 /// ### Example
 ///
 /// #### BAD:

lib/src/lints/avoid_unnecessary_return_variable/avoid_unnecessary_return_variable_rule.dart

@@ -30,8 +30,8 @@ import 'package:solid_lints/src/lints/avoid_unnecessary_return_variable/visitors
 /// ```
 ///
 class AvoidUnnecessaryReturnVariableRule extends AnalysisRule {
-  /// The name of the lint rule.
-  static const _lintName = 'avoid_unnecessary_return_variable';
+  /// The lint rule name. Must be public to generate docs.
+  static const lintName = 'avoid_unnecessary_return_variable';
 
   /// The message shown when the lint is triggered.
   static const String _lintMessage = """
@@ -40,14 +40,14 @@ Rewrite the variable evaluation into return statement instead.""";
 
   /// Lint code.
   static const LintCode _code = LintCode(
-    _lintName,
+    lintName,
     _lintMessage,
   );
 
   /// Creates a new instance of [AvoidUnnecessaryReturnVariableRule]
   AvoidUnnecessaryReturnVariableRule()
     : super(
-        name: _lintName,
+        name: lintName,
         description: _lintMessage,
       );
 

lib/src/lints/avoid_unnecessary_setstate/avoid_unnecessary_set_state_rule.dart

@@ -56,23 +56,23 @@ import 'package:solid_lints/src/lints/avoid_unnecessary_setstate/visitors/avoid_
 /// }
 /// ```
 class AvoidUnnecessarySetStateRule extends AnalysisRule {
-  /// The name of the lint rule.
-  static const _lintName = 'avoid_unnecessary_setstate';
+  /// The lint rule name. Must be public to generate docs.
+  static const lintName = 'avoid_unnecessary_setstate';
 
   /// The message shown when the lint rule is triggered.
   static const _lintMessage = 'Avoid calling unnecessary setState. '
       'Consider changing the state directly.';
 
   /// The lint code for this rule.
   static const _code = LintCode(
-    _lintName,
+    lintName,
     _lintMessage,
   );
 
   /// Creates a new instance of [AvoidUnnecessarySetStateRule].
   AvoidUnnecessarySetStateRule()
       : super(
-          name: _lintName,
+          name: lintName,
           description: _lintMessage,
         );
 

lib/src/lints/avoid_unnecessary_type_assertions/visitors/unnecessary_is_expression_visitor.dart

@@ -8,7 +8,9 @@ import 'package:solid_lints/src/utils/typecast_utils.dart';
 ///
 /// ### Example:
 /// {@template solid_lints.avoid_unnecessary_type_assertions.example_is}
-/// #### BAD:
+/// #### `is` operator
+///
+/// ##### BAD:
 /// ```dart
 /// final testList = [1.0, 2.0, 3.0];
 /// final result = testList is List<double>; // LINT
@@ -18,7 +20,7 @@ import 'package:solid_lints/src/utils/typecast_utils.dart';
 /// final casted = d is double; // LINT
 /// ```
 ///
-/// #### GOOD:
+/// ##### GOOD:
 /// ```dart
 /// final double? nullableD = 2.0;
 /// // casting `Type? is Type` is allowed

lib/src/lints/avoid_unnecessary_type_assertions/visitors/unnecessary_where_type_visitor.dart

@@ -10,13 +10,15 @@ import 'package:solid_lints/src/utils/typecast_utils.dart';
 ///
 /// ### Example:
 /// {@template solid_lints.avoid_unnecessary_type_assertions.example_where}
-/// #### BAD:
+/// #### `whereType` method
+///
+/// ##### BAD:
 /// ```dart
 /// final testList = [1.0, 2.0, 3.0];
 /// testList.whereType<double>(); // LINT
 /// ```
 ///
-/// #### GOOD:
+/// ##### GOOD:
 /// ```dart
 /// final dynamicList = <dynamic>[1.0, 2.0];
 /// dynamicList.whereType<double>();

lib/src/lints/avoid_unrelated_type_assertions/avoid_unrelated_type_assertions_rule.dart

@@ -7,23 +7,23 @@ import 'package:solid_lints/src/lints/avoid_unrelated_type_assertions/visitors/a
 /// A `avoid_unrelated_type_assertions` rule which
 /// warns about unnecessary usage of `as` operator
 class AvoidUnrelatedTypeAssertionsRule extends AnalysisRule {
-  /// The name of the lint rule.
-  static const _lintName = 'avoid_unrelated_type_assertions';
+  /// The lint rule name. Must be public to generate docs.
+  static const lintName = 'avoid_unrelated_type_assertions';
 
   /// The message shown when the lint rule is triggered.
   static const _lintMessage =
       'Avoid unrelated "is" assertion. The result is always "{0}".';
 
   /// Lint code for this rule.
   static const LintCode _code = LintCode(
-    _lintName,
+    lintName,
     _lintMessage,
   );
 
   /// Creates a new instance of [AvoidUnrelatedTypeAssertionsRule].
   AvoidUnrelatedTypeAssertionsRule()
     : super(
-        name: _lintName,
+        name: lintName,
         description: _lintMessage,
       );