Refresh the documentation of EnforcedStyle: omit_parentheses

lib/rubocop/cop/style/method_call_with_args_parentheses.rb

@@ -7,21 +7,19 @@ module Style
       # method calls containing parameters.
       #
       # In the default style (require_parentheses), macro methods are allowed.
-      # Additional methods can be added to the `AllowedMethods`
-      # or `AllowedPatterns` list. These options are
-      # valid only in the default style. Macros can be included by
-      # either setting `IgnoreMacros` to false or adding specific macros to
-      # the `IncludedMacros` list.
+      # Additional methods can be added to the `AllowedMethods` or
+      # `AllowedPatterns` list. These options are valid only in the default
+      # style. Macros can be included by either setting `IgnoreMacros` to false
+      # or adding specific macros to the `IncludedMacros` list.
       #
-      # Precedence of options is all follows:
+      # Precedence of options is as follows:
       #
       # 1. `AllowedMethods`
       # 2. `AllowedPatterns`
       # 3. `IncludedMacros`
       #
-      # eg. If a method is listed in both
-      # `IncludedMacros` and `AllowedMethods`, then the latter takes
-      # precedence (that is, the method is allowed).
+      # If a method is listed in both `IncludedMacros` and `AllowedMethods`,
+      # then the latter takes precedence (that is, the method is allowed).
       #
       # In the alternative style (omit_parentheses), there are three additional
       # options.
@@ -40,14 +38,29 @@ module Style
       #     to `true` allows the presence of parentheses in such a method call
       #     even with arguments.
       #
-      # NOTE: Parentheses are still allowed in cases where omitting them
-      # results in ambiguous or syntactically incorrect code. For example,
-      # parentheses are required around a method with arguments when inside an
-      # endless method definition introduced in Ruby 3.0. Parentheses are also
-      # allowed when forwarding arguments with the triple-dot syntax introduced
-      # in Ruby 2.7 as omitting them starts an endless range.
-      # And Ruby 3.1's hash omission syntax has a case that requires parentheses
-      # because of the following issue: https://bugs.ruby-lang.org/issues/18396.
+      # NOTE: The style of `omit_parentheses` allows parentheses in cases where
+      # omitting them results in ambiguous or syntactically incorrect code.
+      #
+      # Non-exhaustive list of examples:
+      #
+      # - Parentheses are required allowed in method calls with arguments inside
+      #   literals, logical operators, setting default values in position and
+      #   keyword arguments, chaining and more.
+      # - Parentheses are allowed in method calls with arguments inside
+      #   operators to avoid ambiguity.
+      #   triple-dot syntax introduced in Ruby 2.7 as omitting them starts an
+      #   endless range.
+      # - Parentheses are allowed when forwarding arguments with the
+      #   triple-dot syntax introduced in Ruby 2.7 as omitting them starts an
+      #   endless range.
+      # - Parentheses are required in calls with arguments when inside an
+      #   endless method definition introduced in Ruby 3.0.
+      # - Ruby 3.1's hash omission syntax allows parentheses if the method call
+      #   is in conditionals and requires parentheses if the call
+      #   is not the value-returning expression. See
+      #   https://bugs.ruby-lang.org/issues/18396.
+      # - Parentheses are required in anonymous arguments, keyword arguments
+      #   and block passing in Ruby 3.2.
       #
       # @example EnforcedStyle: require_parentheses (default)
       #
@@ -80,34 +93,28 @@ module Style
       #   array.delete e
       #
       #   # bad
-      #   foo.enforce(strict: true)
+      #   action.enforce(strict: true)
       #
       #   # good
-      #   foo.enforce strict: true
+      #   action.enforce strict: true
       #
       #   # good
-      #   # Allows parens for calls that won't produce valid Ruby or be ambiguous.
-      #   model.validate strict(true)
+      #   # Parentheses are allowed for code that can be ambiguous without
+      #   # them.
+      #   action.enforce(condition) || other_condition
       #
       #   # good
-      #   # Allows parens for calls that won't produce valid Ruby or be ambiguous.
+      #   # Parentheses are allowed for calls that won't produce valid Ruby
+      #   # without them.
       #   yield path, File.basename(path)
       #
       #   # good
-      #   # Operators methods calls with parens
-      #   array&.[](index)
-      #
-      #   # good
-      #   # Operators methods without parens, if you prefer
-      #   array.[] index
-      #
-      #   # good
-      #   # Operators methods calls with parens
-      #   array&.[](index)
-      #
-      #   # good
-      #   # Operators methods without parens, if you prefer
-      #   array.[] index
+      #   # Omitting the parentheses in Ruby 3.1 hash omission syntax can lead
+      #   # to ambiguous code. We allow them in conditionals and non-last
+      #   # expressions. See https://bugs.ruby-lang.org/issues/18396
+      #   if meets(criteria:, action:)
+      #     safe_action(action) || dangerous_action(action)
+      #   end
       #
       # @example IgnoreMacros: true (default)
       #