Tweak rules’ docs and messages

spec/ameba/rule/lint/trailing_rescue_exception_spec.cr

@@ -20,7 +20,7 @@ module Ameba::Rule::Lint
     it "fails if trailing rescue has exception name" do
       expect_issue subject, <<-CRYSTAL
         puts "hello" rescue MyException
-                          # ^^^^^^^^^^^ error: Trailing rescues with a path aren't allowed, use a block rescue instead to filter by exception type
+                          # ^^^^^^^^^^^ error: Use a block variant of `rescue` to filter by the exception type
         CRYSTAL
     end
   end

src/ameba/rule/lint/trailing_rescue_exception.cr

@@ -1,30 +1,30 @@
 module Ameba::Rule::Lint
-  # A rule that prohibits the common misconception about how trailing rescue statements work,
-  # preventing Paths (exception class names or otherwise) from being
-  # used as the trailing value. The value after the trailing rescue statement is the
-  # value to use if an exception occurs, not the exception for the rescue to capture.
+  # A rule that prohibits the misconception about how trailing `rescue` statements work,
+  # preventing Paths (exception class names or otherwise) from being used as the
+  # trailing value. The value after the trailing `rescue` statement is the value
+  # to use if an exception occurs, not the exception class to rescue from.
   #
-  # For example, this is considered invalid - if an exception occurs in `method.call`,
-  # `value` will be assigned the value of `MyException`:
+  # For example, this is considered invalid - if an exception occurs,
+  # `response` will be assigned with the value of `IO::Error` instead of `nil`:
   #
   # ```
-  # value = method.call("param") rescue MyException
+  # response = HTTP::Client.get("http://www.example.com") rescue IO::Error
   # ```
   #
-  # And should instead be written as this in order to capture only `MyException` exceptions:
+  # And should instead be written as this in order to capture only `IO::Error` exceptions:
   #
   # ```
-  # value = begin
-  #   method.call("param")
-  # rescue MyException
+  # response = begin
+  #   HTTP::Client.get("http://www.example.com")
+  # rescue IO::Error
   #   "default value"
   # end
   # ```
   #
-  # Or to rescue all exceptions (instead of just `MyException`):
+  # Or to rescue all exceptions (instead of just `IO::Error`):
   #
   # ```
-  # value = method.call("param") rescue "default value"
+  # response = HTTP::Client.get("http://www.example.com") rescue "default value"
   # ```
   #
   # YAML configuration example:
@@ -39,7 +39,7 @@ module Ameba::Rule::Lint
       description "Disallows trailing `rescue` with a path"
     end
 
-    MSG = "Trailing rescues with a path aren't allowed, use a block rescue instead to filter by exception type"
+    MSG = "Use a block variant of `rescue` to filter by the exception type"
 
     def test(source, node : Crystal::ExceptionHandler)
       return unless node.suffix &&

src/ameba/rule/lint/unneeded_disable_directive.cr

@@ -9,7 +9,7 @@ module Ameba::Rule::Lint
   # end
   # ```
   #
-  # as the predicate name is correct and the comment directive does not
+  # As the predicate name is correct and the comment directive does not
   # have any effect, the snippet should be written as the following:
   #
   # ```

src/ameba/rule/lint/unused_literal.cr

@@ -35,8 +35,6 @@ module Ameba::Rule::Lint
   #     true
   #   end
   # end
-  #
-  # my_proc = -> : Bool { true }
   # ```
   #
   # YAML configuration example:

src/ameba/rule/typing/proc_literal_return_type_restriction.cr

@@ -1,24 +1,24 @@
 module Ameba::Rule::Typing
   # A rule that enforces that `Proc` literals have a return type.
   #
-  # For example, these are considered valid:
+  # For example, these are considered invalid:
   #
   # ```
-  # greeter = ->(name : String) : String { "Hello #{name}" }
+  # greeter = ->(name : String) { "Hello #{name}" }
   # ```
   #
   # ```
-  # task = -> : Task { Task.new("execute this command") }
+  # task = -> { Task.new("execute this command") }
   # ```
   #
-  # And these are invalid:
+  # And these are valid:
   #
   # ```
-  # greeter = ->(name : String) { "Hello #{name}" }
+  # greeter = ->(name : String) : String { "Hello #{name}" }
   # ```
   #
   # ```
-  # task = -> { Task.new("execute this command") }
+  # task = -> : Task { Task.new("execute this command") }
   # ```
   #
   # YAML configuration example:
@@ -30,7 +30,7 @@ module Ameba::Rule::Typing
   class ProcLiteralReturnTypeRestriction < Base
     properties do
       since_version "1.7.0"
-      description "Disallows Proc literals without return type restrictions"
+      description "Disallows proc literals without return type restriction"
       enabled false
     end