Merge pull request #2116 from rubocop/doc

Enhance documentation for autocorrect safety in ExampleWording cop

Author: ydah

docs/modules/ROOT/pages/cops_rspec.adoc

@@ -1946,13 +1946,26 @@ Checks for common mistakes in example descriptions.
 This cop will correct docstrings that begin with 'should' and 'it'.
 This cop will also look for insufficient examples and call them out.
 
-The autocorrect is experimental - use with care! It can be configured
-with CustomTransform (e.g. have => has) and IgnoredWords (e.g. only).
-
 Use the DisallowedExamples setting to prevent unclear or insufficient
 descriptions. Please note that this config will not be treated as
 case sensitive.
 
+[#safety-rspecexamplewording]
+=== Safety
+
+The autocorrect is experimental - use with care! It can be configured
+with CustomTransform (e.g. have => has) and IgnoredWords (e.g. only).
+
+While the autocorrect will not break your code (it only modifies test
+description strings, not the actual test logic), it may produce
+grammatically incorrect English in some cases. Always review the diff
+when using autocorrect to ensure the descriptions remain natural and
+accurate.
+
+This is not classified as an unsafe autocorrect because it does not
+affect code behavior, but manual review of changes is strongly
+recommended.
+
 [#examples-rspecexamplewording]
 === Examples
 

lib/rubocop/cop/rspec/example_wording.rb

@@ -10,8 +10,19 @@ module RSpec
       #
       # @see http://betterspecs.org/#should
       #
-      # The autocorrect is experimental - use with care! It can be configured
-      # with CustomTransform (e.g. have => has) and IgnoredWords (e.g. only).
+      # @safety
+      #   The autocorrect is experimental - use with care! It can be configured
+      #   with CustomTransform (e.g. have => has) and IgnoredWords (e.g. only).
+      #
+      #   While the autocorrect will not break your code (it only modifies test
+      #   description strings, not the actual test logic), it may produce
+      #   grammatically incorrect English in some cases. Always review the diff
+      #   when using autocorrect to ensure the descriptions remain natural and
+      #   accurate.
+      #
+      #   This is not classified as an unsafe autocorrect because it does not
+      #   affect code behavior, but manual review of changes is strongly
+      #   recommended.
       #
       # Use the DisallowedExamples setting to prevent unclear or insufficient
       # descriptions. Please note that this config will not be treated as