rubocop 1.84.2 → 1.86.2

data/lib/rubocop/cop/mixin/hash_transform_method.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'hash_transform_method/autocorrection'
+
 module RuboCop
   module Cop
     # Common functionality for Style/HashTransformKeys and
@@ -27,68 +29,16 @@ module RuboCop
         end
       end
 
-      # Internal helper class to hold autocorrect data
-      Autocorrection = Struct.new(:match, :block_node, :leading, :trailing) do
-        def self.from_each_with_object(node, match)
-          new(match, node, 0, 0)
-        end
-
-        def self.from_hash_brackets_map(node, match)
-          new(match, node.children.last, 'Hash['.length, ']'.length)
-        end
-
-        def self.from_map_to_h(node, match)
-          if node.parent&.block_type? && node.parent.send_node == node
-            strip_trailing_chars = 0
-          else
-            map_range = node.children.first.source_range
-            node_range = node.source_range
-            strip_trailing_chars = node_range.end_pos - map_range.end_pos
-          end
-
-          new(match, node.children.first, 0, strip_trailing_chars)
-        end
-
-        def self.from_to_h(node, match)
-          new(match, node, 0, 0)
-        end
-
-        def strip_prefix_and_suffix(node, corrector)
-          expression = node.source_range
-          corrector.remove_leading(expression, leading)
-          corrector.remove_trailing(expression, trailing)
-        end
-
-        def set_new_method_name(new_method_name, corrector)
-          range = block_node.send_node.loc.selector
-          if (send_end = block_node.send_node.loc.end)
-            # If there are arguments (only true in the `each_with_object`
-            # case)
-            range = range.begin.join(send_end)
-          end
-          corrector.replace(range, new_method_name)
-        end
-
-        def set_new_arg_name(transformed_argname, corrector)
-          corrector.replace(block_node.arguments, "|#{transformed_argname}|")
-        end
-
-        def set_new_body_expression(transforming_body_expr, corrector)
-          body_source = transforming_body_expr.source
-          if transforming_body_expr.hash_type? && !transforming_body_expr.braces?
-            body_source = "{ #{body_source} }"
-          end
-
-          corrector.replace(block_node.body, body_source)
-        end
-      end
-
-      # @!method array_receiver?(node)
-      def_node_matcher :array_receiver?, <<~PATTERN
-        {(array ...) (send _ :each_with_index) (send _ :with_index _ ?) (send _ :zip ...)}
+      # @!method hash_receiver?(node)
+      def_node_matcher :hash_receiver?, <<~PATTERN
+        {(hash ...)
+         (send _ {:to_h :to_hash :merge :merge! :update :invert :except :tally} ...)
+         (block (send _ {:group_by :to_h :tally :transform_keys :transform_keys!
+                         :transform_values :transform_values!}) ...)
+         (block (send _ :each_with_object (hash)) ...)}
       PATTERN
 
-      def on_block(node) # rubocop:disable InternalAffairs/NumblockHandler
+      def on_block(node) # rubocop:disable InternalAffairs/NumblockHandler, InternalAffairs/ItblockHandler
         on_bad_each_with_object(node) do |*match|
           handle_possible_offense(node, match, 'each_with_object')
         end

data/lib/rubocop/cop/mixin.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop # rubocop:disable Style/Documentation
+    # Autoloads mixin modules included by cops. Mixins are autoloaded to reduce the number of
+    # requires because they're used only when the relevant cop class is loaded.
+
+    autoload :ArrayMinSize, 'rubocop/cop/mixin/array_min_size'
+    autoload :ArraySyntax, 'rubocop/cop/mixin/array_syntax'
+    autoload :Alignment, 'rubocop/cop/mixin/alignment'
+    autoload :AllowedIdentifiers, 'rubocop/cop/mixin/allowed_identifiers'
+    autoload :AllowedMethods, 'rubocop/cop/mixin/allowed_methods'
+    autoload :AllowedPattern, 'rubocop/cop/mixin/allowed_pattern'
+    autoload :AllowedReceivers, 'rubocop/cop/mixin/allowed_receivers'
+    autoload :ForbiddenIdentifiers, 'rubocop/cop/mixin/forbidden_identifiers'
+    autoload :ForbiddenPattern, 'rubocop/cop/mixin/forbidden_pattern'
+    autoload :AutoCorrector, 'rubocop/cop/mixin/auto_corrector' # rubocop:todo Naming/InclusiveLanguage
+    autoload :CheckAssignment, 'rubocop/cop/mixin/check_assignment'
+    autoload :CheckLineBreakable, 'rubocop/cop/mixin/check_line_breakable'
+    autoload :CheckSingleLineSuitability, 'rubocop/cop/mixin/check_single_line_suitability'
+    autoload :ConfigurableMax, 'rubocop/cop/mixin/configurable_max'
+    autoload :CodeLength, 'rubocop/cop/mixin/code_length'
+    autoload :ConfigurableEnforcedStyle, 'rubocop/cop/mixin/configurable_enforced_style'
+    autoload :ConfigurableFormatting, 'rubocop/cop/mixin/configurable_formatting'
+    autoload :ConfigurableNaming, 'rubocop/cop/mixin/configurable_naming'
+    autoload :ConfigurableNumbering, 'rubocop/cop/mixin/configurable_numbering'
+    autoload :DigHelp, 'rubocop/cop/mixin/dig_help'
+    autoload :DocumentationComment, 'rubocop/cop/mixin/documentation_comment'
+    autoload :Duplication, 'rubocop/cop/mixin/duplication'
+    autoload :RangeHelp, 'rubocop/cop/mixin/range_help'
+    autoload :AnnotationComment, 'rubocop/cop/mixin/annotation_comment'
+    autoload :EmptyParameter, 'rubocop/cop/mixin/empty_parameter'
+    autoload :EndKeywordAlignment, 'rubocop/cop/mixin/end_keyword_alignment'
+    autoload :EndlessMethodRewriter, 'rubocop/cop/mixin/endless_method_rewriter'
+    autoload :EnforceSuperclass, 'rubocop/cop/mixin/enforce_superclass'
+    autoload :FirstElementLineBreak, 'rubocop/cop/mixin/first_element_line_break'
+    autoload :FrozenStringLiteral, 'rubocop/cop/mixin/frozen_string_literal'
+    autoload :GemDeclaration, 'rubocop/cop/mixin/gem_declaration'
+    autoload :GemspecHelp, 'rubocop/cop/mixin/gemspec_help'
+    autoload :HashAlignmentStyles, 'rubocop/cop/mixin/hash_alignment_styles'
+    autoload :HashSubset, 'rubocop/cop/mixin/hash_subset'
+    autoload :HashTransformMethod, 'rubocop/cop/mixin/hash_transform_method'
+    autoload :IntegerNode, 'rubocop/cop/mixin/integer_node'
+    autoload :Interpolation, 'rubocop/cop/mixin/interpolation'
+    autoload :LineLengthHelp, 'rubocop/cop/mixin/line_length_help'
+    autoload :MatchRange, 'rubocop/cop/mixin/match_range'
+    autoload :HashShorthandSyntax, 'rubocop/cop/mixin/hash_shorthand_syntax'
+    autoload :MethodComplexity, 'rubocop/cop/mixin/method_complexity'
+    autoload :MethodPreference, 'rubocop/cop/mixin/method_preference'
+    autoload :MinBodyLength, 'rubocop/cop/mixin/min_body_length'
+    autoload :MinBranchesCount, 'rubocop/cop/mixin/min_branches_count'
+    autoload :MultilineElementIndentation, 'rubocop/cop/mixin/multiline_element_indentation'
+    autoload :MultilineElementLineBreaks, 'rubocop/cop/mixin/multiline_element_line_breaks'
+    autoload :MultilineExpressionIndentation, 'rubocop/cop/mixin/multiline_expression_indentation'
+    autoload :MultilineLiteralBraceLayout, 'rubocop/cop/mixin/multiline_literal_brace_layout'
+    autoload :NegativeConditional, 'rubocop/cop/mixin/negative_conditional'
+    autoload :Heredoc, 'rubocop/cop/mixin/heredoc'
+    autoload :NilMethods, 'rubocop/cop/mixin/nil_methods'
+    autoload :OnNormalIfUnless, 'rubocop/cop/mixin/on_normal_if_unless'
+    autoload :OrderedGemNode, 'rubocop/cop/mixin/ordered_gem_node'
+    autoload :Parentheses, 'rubocop/cop/mixin/parentheses'
+    autoload :PercentArray, 'rubocop/cop/mixin/percent_array'
+    autoload :PercentLiteral, 'rubocop/cop/mixin/percent_literal'
+    autoload :PrecedingFollowingAlignment, 'rubocop/cop/mixin/preceding_following_alignment'
+    autoload :PreferredDelimiters, 'rubocop/cop/mixin/preferred_delimiters'
+    autoload :RationalLiteral, 'rubocop/cop/mixin/rational_literal'
+    autoload :RequireLibrary, 'rubocop/cop/mixin/require_library'
+    autoload :RescueNode, 'rubocop/cop/mixin/rescue_node'
+    autoload :SafeAssignment, 'rubocop/cop/mixin/safe_assignment'
+    autoload :SpaceAfterPunctuation, 'rubocop/cop/mixin/space_after_punctuation'
+    autoload :SpaceBeforePunctuation, 'rubocop/cop/mixin/space_before_punctuation'
+    autoload :SurroundingSpace, 'rubocop/cop/mixin/surrounding_space'
+    autoload :StatementModifier, 'rubocop/cop/mixin/statement_modifier'
+    autoload :StringHelp, 'rubocop/cop/mixin/string_help'
+    autoload :StringLiteralsHelp, 'rubocop/cop/mixin/string_literals_help'
+    autoload :SymbolHelp, 'rubocop/cop/mixin/symbol_help'
+    autoload :TargetRubyVersion, 'rubocop/cop/mixin/target_ruby_version'
+    autoload :TrailingBody, 'rubocop/cop/mixin/trailing_body'
+    autoload :TrailingComma, 'rubocop/cop/mixin/trailing_comma'
+    autoload :UncommunicativeName, 'rubocop/cop/mixin/uncommunicative_name'
+    autoload :VisibilityHelp, 'rubocop/cop/mixin/visibility_help'
+    autoload :CommentsHelp, 'rubocop/cop/mixin/comments_help'
+    autoload :DefNode, 'rubocop/cop/mixin/def_node'
+  end
+end

data/lib/rubocop/cop/naming/block_parameter_name.rb

@@ -38,7 +38,7 @@ module RuboCop
       class BlockParameterName < Base
         include UncommunicativeName
 
-        def on_block(node) # rubocop:disable InternalAffairs/NumblockHandler
+        def on_block(node) # rubocop:disable InternalAffairs/NumblockHandler, InternalAffairs/ItblockHandler
           return unless node.arguments?
 
           check(node, node.arguments)

data/lib/rubocop/cop/naming/memoized_instance_variable_name.rb

@@ -109,7 +109,7 @@ module RuboCop
       #     @_foo = calculate_expensive_thing
       #   end
       #
-      # @example EnforcedStyleForLeadingUnderscores :optional
+      # @example EnforcedStyleForLeadingUnderscores: optional
       #   # bad
       #   def foo
       #     @something ||= calculate_expensive_thing

data/lib/rubocop/cop/offense.rb

@@ -98,6 +98,14 @@ module RuboCop
         freeze
       end
 
+      def marshal_dump
+        [@severity, @location, @message, @cop_name, @status]
+      end
+
+      def marshal_load(array)
+        @severity, @location, @message, @cop_name, @status = array
+      end
+
       # @api public
       #
       # @!attribute [r] correctable?

data/lib/rubocop/cop/registry.rb

@@ -16,7 +16,7 @@ module RuboCop
     end
 
     # Registry that tracks all cops by their badge and department.
-    class Registry
+    class Registry # rubocop:disable Metrics/ClassLength
       include Enumerable
 
       def self.all
@@ -46,18 +46,18 @@ module RuboCop
         global.qualify_badge(badge).first == badge
       end
 
-      attr_reader :options
+      attr_reader :options, :warnings
 
       def initialize(cops = [], options = {})
-        @registry = {}
-        @departments = {}
-        @cops_by_cop_name = Hash.new { |hash, key| hash[key] = [] }
+        @departments = Set.new
+        @cops_by_badge = {}
 
         @enrollment_queue = cops
         @options = options
 
         @enabled_cache = {}.compare_by_identity
         @disabled_cache = {}.compare_by_identity
+        @warnings = {}
       end
 
       def enlist(cop)
@@ -71,22 +71,17 @@ module RuboCop
       # @return [Array<Symbol>] list of departments for current cops.
       def departments
         clear_enrollment_queue
-        @departments.keys
+        @departments.to_a
       end
 
       # @return [Registry] Cops for that specific department.
       def with_department(department)
-        clear_enrollment_queue
-        with(@departments.fetch(department, []))
+        with(cops.select { |cop| cop.department == department })
       end
 
       # @return [Registry] Cops not for a specific department.
       def without_department(department)
-        clear_enrollment_queue
-        without_department = @departments.dup
-        without_department.delete(department)
-
-        with(without_department.values.flatten)
+        with(cops.reject { |cop| cop.department == department })
       end
 
       # @return [Boolean] Checks if given name is department
@@ -132,7 +127,7 @@ module RuboCop
       # @return [String] Qualified cop name
       def qualified_cop_name(name, path, warn: true)
         badge = Badge.parse(name)
-        print_warning(name, path) if warn && department_missing?(badge, name)
+        print_department_missing_warning(name, path) if warn && department_missing?(badge, name)
         return name if registered?(badge)
 
         potential_badges = qualify_badge(badge)
@@ -148,42 +143,42 @@ module RuboCop
         !badge.qualified? && unqualified_cop_names.include?(name)
       end
 
-      def print_warning(name, path)
-        message = "#{path}: Warning: no department given for #{name}."
+      def print_department_missing_warning(name, path)
+        message = "no department given for #{name}."
         if path.end_with?('.rb')
           message += ' Run `rubocop -a --only Migration/DepartmentName` to fix.'
         end
-        warn message
+        emit_warning(path, message)
       end
 
       def unqualified_cop_names
         clear_enrollment_queue
         @unqualified_cop_names ||=
-          Set.new(@cops_by_cop_name.keys.map { |qn| File.basename(qn) }) <<
+          Set.new(@cops_by_badge.keys.map { |badge| File.basename(badge.to_s) }) <<
           'RedundantCopDisableDirective'
       end
 
       def qualify_badge(badge)
         clear_enrollment_queue
         @departments
-          .map { |department, _| badge.with_department(department) }
+          .map { |department| badge.with_department(department) }
           .select { |potential_badge| registered?(potential_badge) }
       end
 
       # @return [Hash{String => Array<Class>}]
       def to_h
         clear_enrollment_queue
-        @cops_by_cop_name
+        @cops_by_badge.to_h { |_badge, cop| [cop.cop_name, [cop]] }
       end
 
       def cops
         clear_enrollment_queue
-        @registry.values
+        @cops_by_badge.values
       end
 
       def length
         clear_enrollment_queue
-        @registry.size
+        @cops_by_badge.size
       end
 
       def enabled(config)
@@ -218,7 +213,8 @@ module RuboCop
       end
 
       def names
-        cops.map(&:cop_name)
+        clear_enrollment_queue
+        @cops_by_badge.keys.map(&:to_s)
       end
 
       def cops_for_department(department)
@@ -235,7 +231,7 @@ module RuboCop
 
       def sort!
         clear_enrollment_queue
-        @registry = @registry.sort_by { |badge, _| badge.cop_name }.to_h
+        @cops_by_badge = @cops_by_badge.sort_by { |badge, _cop| badge.cop_name }.to_h
 
         self
       end
@@ -251,7 +247,9 @@ module RuboCop
       # @param [String] cop_name
       # @return [Class, nil]
       def find_by_cop_name(cop_name)
-        to_h[cop_name].first
+        clear_enrollment_queue
+        badge = Badge.parse(cop_name)
+        @cops_by_badge[badge]
       end
 
       # When a cop name is given returns a single-element array with the cop class.
@@ -274,6 +272,10 @@ module RuboCop
         attr_reader :global
       end
 
+      def warnings?(path)
+        @warnings[path]
+      end
+
       private
 
       def initialize_copy(reg)
@@ -284,10 +286,8 @@ module RuboCop
         return if @enrollment_queue.empty?
 
         @enrollment_queue.each do |cop|
-          @registry[cop.badge] = cop
-          @departments[cop.department] ||= []
-          @departments[cop.department] << cop
-          @cops_by_cop_name[cop.cop_name] << cop
+          @cops_by_badge[cop.badge] = cop
+          @departments << cop.department
         end
         @enrollment_queue = []
       end
@@ -297,21 +297,23 @@ module RuboCop
       end
 
       def resolve_badge(given_badge, real_badge, source_path, warn: true)
-        unless given_badge.match?(real_badge)
-          path = PathUtil.smart_path(source_path)
-
-          if warn
-            warn("#{path}: #{given_badge} has the wrong namespace - " \
-                 "replace it with #{given_badge.with_department(real_badge.department)}")
-          end
+        if warn && !given_badge.match?(real_badge)
+          emit_warning(source_path,
+                       "#{given_badge} has the wrong namespace - " \
+                       "replace it with #{given_badge.with_department(real_badge.department)}")
         end
 
         real_badge.to_s
       end
 
+      def emit_warning(path, message)
+        Registry.global.warnings[path] = true
+        warn "#{PathUtil.smart_path(path)}: Warning: #{message}"
+      end
+
       def registered?(badge)
         clear_enrollment_queue
-        @registry.key?(badge)
+        @cops_by_badge.key?(badge)
       end
     end
   end

data/lib/rubocop/cop/security/eval.rb

@@ -3,15 +3,28 @@
 module RuboCop
   module Cop
     module Security
-      # Checks for the use of `Kernel#eval` and `Binding#eval`.
+      # Checks for the use of `Kernel#eval` and `Binding#eval` with
+      # dynamic strings as arguments. Evaluating non-literal strings
+      # can enable code injection attacks and makes it difficult to
+      # reason about what code will actually be executed.
+      #
+      # Calls to `eval` with literal strings are not flagged by this cop,
+      # as they do not pose the same injection risk.
       #
       # @example
       #
       #   # bad
-      #
       #   eval(something)
       #   binding.eval(something)
       #   Kernel.eval(something)
+      #
+      #   # good - use safer alternatives
+      #   obj.public_send(method_name)
+      #   obj.send(method_name, *args)
+      #
+      #   # good - literal strings are allowed
+      #   eval("1 + 1")
+      #   binding.eval("foo")
       class Eval < Base
         MSG = 'The use of `eval` is a serious security risk.'
         RESTRICT_ON_SEND = %i[eval].freeze

data/lib/rubocop/cop/style/access_modifier_declarations.rb

@@ -348,8 +348,20 @@ module RuboCop
 
         def remove_modifier_node_within_begin(corrector, modifier_node, begin_node)
           def_node = begin_node.children[begin_node.children.index(modifier_node) + 1]
-          range = modifier_node.source_range.begin.join(def_node.source_range.begin)
-          corrector.remove(range)
+          # Stop the removal range at the first comment that precedes the def, if
+          # any exist. Without this, comments between the modifier and the def are
+          # dropped because they fall inside the removed range.
+          end_pos = first_comment_or_node_start(def_node)
+          corrector.remove(modifier_node.source_range.begin.join(end_pos))
+        end
+
+        def first_comment_or_node_start(node)
+          preceding = processed_source.ast_with_comments[node].select do |comment|
+            comment.loc.line < node.loc.line
+          end
+          return node.source_range.begin if preceding.empty?
+
+          preceding.first.source_range.begin
         end
 
         def def_source(node, def_nodes)

data/lib/rubocop/cop/style/accessor_grouping.rb

@@ -4,8 +4,10 @@ module RuboCop
   module Cop
     module Style
       # Checks for grouping of accessors in `class` and `module` bodies.
-      # By default it enforces accessors to be placed in grouped declarations,
-      # but it can be configured to enforce separating them in multiple declarations.
+      # By default it enforces accessors to be placed in grouped
+      # declarations, reducing boilerplate. It can also be configured
+      # to enforce separating them into individual declarations for
+      # easier diffing and per-attribute documentation.
       #
       # NOTE: If there is a method call before the accessor method it is always allowed
       # as it might be intended like Sorbet.

data/lib/rubocop/cop/style/alias.rb

@@ -4,7 +4,10 @@ module RuboCop
   module Cop
     module Style
       # Enforces the use of either `#alias` or `#alias_method`
-      # depending on configuration.
+      # depending on configuration. Consistent use of one or the
+      # other prevents confusion about their different semantics
+      # (e.g., `alias` is resolved at parse time, while `alias_method`
+      # is resolved at runtime).
       # It also flags uses of `alias :symbol` rather than `alias bareword`.
       #
       # However, it will always enforce `method_alias` when used `alias`

data/lib/rubocop/cop/style/and_or.rb

@@ -128,6 +128,7 @@ module RuboCop
 
         def correct_other(node, corrector)
           return if node.parenthesized_call?
+          return if node.children.empty? && node.equal?(node.parent.children.last)
 
           corrector.wrap(node, '(', ')')
         end

data/lib/rubocop/cop/style/arguments_forwarding.rb

@@ -424,21 +424,39 @@ module RuboCop
           end
 
           def forwarded_rest_arg
-            return nil if referenced_rest_arg?
+            return @forwarded_rest_arg if defined?(@forwarded_rest_arg)
 
-            arguments.find { |arg| forwarded_rest_arg?(arg, @rest_arg_name) }
+            @forwarded_rest_arg = if referenced_rest_arg?
+                                    nil
+                                  else
+                                    arguments.find do |arg|
+                                      forwarded_rest_arg?(arg, @rest_arg_name)
+                                    end
+                                  end
           end
 
           def forwarded_kwrest_arg
-            return nil if referenced_kwrest_arg?
+            return @forwarded_kwrest_arg if defined?(@forwarded_kwrest_arg)
 
-            arguments.filter_map { |arg| extract_forwarded_kwrest_arg(arg, @kwrest_arg_name) }.first
+            @forwarded_kwrest_arg = if referenced_kwrest_arg?
+                                      nil
+                                    else
+                                      arguments.filter_map do |arg|
+                                        extract_forwarded_kwrest_arg(arg, @kwrest_arg_name)
+                                      end.first
+                                    end
           end
 
           def forwarded_block_arg
-            return nil if referenced_block_arg?
-
-            arguments.find { |arg| forwarded_block_arg?(arg, @block_arg_name) }
+            return @forwarded_block_arg if defined?(@forwarded_block_arg)
+
+            @forwarded_block_arg = if referenced_block_arg?
+                                     nil
+                                   else
+                                     arguments.find do |arg|
+                                       forwarded_block_arg?(arg, @block_arg_name)
+                                     end
+                                   end
           end
 
           def classification

data/lib/rubocop/cop/style/array_join.rb

@@ -3,9 +3,11 @@
 module RuboCop
   module Cop
     module Style
-      # Checks for uses of "*" as a substitute for _join_.
+      # Checks for uses of `*` as a substitute for `Array#join`.
+      # Using `join` is clearer about intent and more readable than
+      # overloading the `*` operator for string conversion.
       #
-      # Not all cases can reliably checked, due to Ruby's dynamic
+      # Not all cases can be reliably checked, due to Ruby's dynamic
       # types, so we consider only cases when the first argument is an
       # array literal or the second is a string literal.
       #

data/lib/rubocop/cop/style/ascii_comments.rb

@@ -4,8 +4,11 @@ module RuboCop
   module Cop
     module Style
       # Checks for non-ascii (non-English) characters
-      # in comments. You could set an array of allowed non-ascii chars in
-      # `AllowedChars` attribute (copyright notice "©" by default).
+      # in comments. Non-ascii characters can cause issues with
+      # portability and encoding across different environments
+      # and editors. You could set an array of allowed non-ascii
+      # chars in `AllowedChars` attribute (copyright notice "©"
+      # by default).
       #
       # @example
       #   # bad
@@ -49,7 +52,7 @@ module RuboCop
         end
 
         def allowed_non_ascii_chars
-          cop_config['AllowedChars'] || []
+          @allowed_non_ascii_chars ||= (cop_config['AllowedChars'] || []).freeze
         end
       end
     end

data/lib/rubocop/cop/style/attr.rb

@@ -3,10 +3,13 @@
 module RuboCop
   module Cop
     module Style
-      # Checks for uses of Module#attr.
+      # Checks for uses of `Module#attr`. The `attr` method has confusing
+      # behavior: with a single argument it creates a reader (like `attr_reader`),
+      # but with a second boolean argument it creates an accessor (deprecated in
+      # Ruby 1.9). Use `attr_reader` or `attr_accessor` to make intent explicit.
       #
       # @example
-      #   # bad - creates a single attribute accessor (deprecated in Ruby 1.9)
+      #   # bad
       #   attr :something, true
       #   attr :one, :two, :three # behaves as attr_reader
       #

data/lib/rubocop/cop/style/bare_percent_literals.rb

@@ -3,7 +3,9 @@
 module RuboCop
   module Cop
     module Style
-      # Checks if usage of %() or %Q() matches configuration.
+      # Checks if usage of `%()` or `%Q()` matches configuration.
+      # Consistent use of one style makes the codebase easier
+      # to read.
       #
       # @example EnforcedStyle: bare_percent (default)
       #   # bad

data/lib/rubocop/cop/style/begin_block.rb

@@ -3,7 +3,9 @@
 module RuboCop
   module Cop
     module Style
-      # Checks for BEGIN blocks.
+      # Checks for `BEGIN` blocks. They are Perl-style constructs that execute
+      # code before the rest of the file is parsed, making the control flow
+      # harder to follow and reason about.
       #
       # @example
       #   # bad