Cleanup docs

src/ameba/formatter/base_formatter.cr

@@ -17,13 +17,13 @@ module Ameba::Formatter
     # A list of sources to inspect is passed as an argument.
     def started(sources); end
 
-    # Callback that indicates when source inspection is finished.
+    # Callback that indicates when source inspection is started.
     # A corresponding source is passed as an argument.
-    def source_finished(source : Source); end
+    def source_started(source : Source); end
 
     # Callback that indicates when source inspection is finished.
     # A corresponding source is passed as an argument.
-    def source_started(source : Source); end
+    def source_finished(source : Source); end
 
     # Callback that indicates when inspection is finished.
     # A list of inspected sources is passed as an argument.

src/ameba/rule/base.cr

@@ -32,14 +32,15 @@ module Ameba::Rule
     # This method is designed to test the source passed in. If source has issues
     # that are tested by this rule, it should add an issue.
     #
-    # Be default it uses a node visitor to traverse all the nodes in the source.
+    # By default it uses a node visitor to traverse all the nodes in the source.
+    #
     # NOTE: Must be overridden for other type of rules.
     def test(source : Source)
       AST::NodeVisitor.new self, source
     end
 
+    # NOTE: Can't be abstract
     def test(source : Source, node : Crystal::ASTNode, *opts)
-      # can't be abstract
     end
 
     # A convenient addition to `#test` method that does the same

src/ameba/rule/naming/block_parameter_name.cr

@@ -41,7 +41,7 @@ module Ameba::Rule::Naming
     end
 
     private def valid_name?(name)
-      return true if name.blank? # happens with compound names like `(arg1, arg2)`
+      return true if name.blank? # TODO: handle unpacked variables
       return true if name.in?(allowed_names)
 
       return false if name.in?(forbidden_names)

src/ameba/rule/style/verbose_block.cr

@@ -230,7 +230,7 @@ module Ameba::Rule::Style
       # we filter out the blocks that are of call type - `i.to_i64.odd?`
       return unless (body = block.body).is_a?(Crystal::Call)
 
-      # we need to "unwind" the chain calls, so the final receiver object
+      # we need to "unwind" the call chain, so the final receiver object
       # ends up being a variable - `i`
       obj = body.obj
       while obj.is_a?(Crystal::Call)