feat(no_empty_block): add allow_comments

allows excluding methods that contain any comments

Author: Andrew-Bekhiet

lib/src/lints/no_empty_block/models/no_empty_block_parameters.dart

@@ -3,18 +3,25 @@ import 'package:solid_lints/src/common/parameters/excluded_identifiers_list_para
 /// A data model class that represents the "no empty block" lint input
 /// parameters.
 class NoEmptyBlockParameters {
+  static const _allowCommentsConfig = 'allow_comments';
+
   /// A list of methods that should be excluded from the lint.
   final ExcludedIdentifiersListParameter exclude;
 
+  /// Whether to exclude empty blocks that contain any comments.
+  final bool allowComments;
+
   /// Constructor for [NoEmptyBlockParameters] model
   NoEmptyBlockParameters({
     required this.exclude,
+    required this.allowComments,
   });
 
   /// Method for creating from json data
   factory NoEmptyBlockParameters.fromJson(Map<String, dynamic> json) {
     return NoEmptyBlockParameters(
       exclude: ExcludedIdentifiersListParameter.defaultFromJson(json),
+      allowComments: json[_allowCommentsConfig] as bool? ?? false,
     );
   }
 }

lib/src/lints/no_empty_block/no_empty_block_rule.dart

@@ -81,7 +81,9 @@ class NoEmptyBlockRule extends SolidLintRule<NoEmptyBlockParameters> {
       final isIgnored = config.parameters.exclude.shouldIgnore(node);
       if (isIgnored) return;
 
-      final visitor = NoEmptyBlockVisitor();
+      final visitor = NoEmptyBlockVisitor(
+        allowComments: config.parameters.allowComments,
+      );
       node.accept(visitor);
 
       for (final emptyBlock in visitor.emptyBlocks) {

lib/src/lints/no_empty_block/visitors/no_empty_block_visitor.dart

@@ -29,8 +29,16 @@ const _todoComment = 'TODO';
 /// The AST visitor that will find all empty blocks, excluding catch blocks
 /// and blocks containing [_todoComment]
 class NoEmptyBlockVisitor extends RecursiveAstVisitor<void> {
+  final bool _allowComments;
+
   final _emptyBlocks = <Block>[];
 
+  /// Constructor for [NoEmptyBlockVisitor]
+  /// [_allowComments] indicates whether to allow empty blocks that contain
+  /// any comments
+  NoEmptyBlockVisitor({required bool allowComments})
+      : _allowComments = allowComments;
+
   /// All empty blocks
   Iterable<Block> get emptyBlocks => _emptyBlocks;
 
@@ -40,11 +48,15 @@ class NoEmptyBlockVisitor extends RecursiveAstVisitor<void> {
 
     if (node.statements.isNotEmpty) return;
     if (node.parent is CatchClause) return;
+    if (_allowComments && _isPrecedingCommentAny(node)) return;
     if (_isPrecedingCommentToDo(node)) return;
 
     _emptyBlocks.add(node);
   }
 
   static bool _isPrecedingCommentToDo(Block node) =>
       node.endToken.precedingComments?.lexeme.contains(_todoComment) ?? false;
+
+  static bool _isPrecedingCommentAny(Block node) =>
+      node.endToken.precedingComments != null;
 }

lint_test/analysis_options.yaml

@@ -9,7 +9,7 @@ custom_lint:
       exclude:
         - class_name: Exclude
           method_name: excludeMethod
-        - method_name: excludeMethod      
+        - method_name: excludeMethod
     - number_of_parameters:
       max_parameters: 2
       exclude:
@@ -24,7 +24,7 @@ custom_lint:
     - avoid_global_state
     - avoid_returning_widgets:
       exclude:
-        - class_name: ExcludeWidget 
+        - class_name: ExcludeWidget
           method_name: excludeWidgetMethod
         - method_name: excludeMethod
     - avoid_unnecessary_setstate
@@ -34,16 +34,17 @@ custom_lint:
     - avoid_unrelated_type_assertions
     - avoid_unused_parameters:
       exclude:
-        - class_name: Exclude 
+        - class_name: Exclude
           method_name: excludeMethod
         - method_name: excludeMethod
         - simpleMethodName
         - SimpleClassName
         - exclude
     - newline_before_return
     - no_empty_block:
+      allow_comments: true
       exclude:
-        - class_name: Exclude 
+        - class_name: Exclude
           method_name: excludeMethod
         - method_name: excludeMethod
     - no_equal_then_else

lint_test/no_empty_block_test.dart

@@ -57,3 +57,15 @@ class Exclude {
   // no lint
   void excludeMethod() {}
 }
+
+// no lint
+void emptyMethodWithComments() {
+  // comment explaining why this block is empty
+}
+
+void anotherExample() {
+  // no lint
+  nestedFun(() {
+    // explain why this block is empty
+  });
+}