Skip to content

Commit e63ee9a

Browse files
committed
Enhance documentation for autocorrect safety in ExampleWording cop
Fixes: #2058
1 parent 1872722 commit e63ee9a

File tree

2 files changed

+29
-5
lines changed

2 files changed

+29
-5
lines changed

docs/modules/ROOT/pages/cops_rspec.adoc

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1946,13 +1946,26 @@ Checks for common mistakes in example descriptions.
19461946
This cop will correct docstrings that begin with 'should' and 'it'.
19471947
This cop will also look for insufficient examples and call them out.
19481948
1949-
The autocorrect is experimental - use with care! It can be configured
1950-
with CustomTransform (e.g. have => has) and IgnoredWords (e.g. only).
1951-
19521949
Use the DisallowedExamples setting to prevent unclear or insufficient
19531950
descriptions. Please note that this config will not be treated as
19541951
case sensitive.
19551952
1953+
[#safety-rspecexamplewording]
1954+
=== Safety
1955+
1956+
The autocorrect is experimental - use with care! It can be configured
1957+
with CustomTransform (e.g. have => has) and IgnoredWords (e.g. only).
1958+
1959+
While the autocorrect will not break your code (it only modifies test
1960+
description strings, not the actual test logic), it may produce
1961+
grammatically incorrect English in some cases. Always review the diff
1962+
when using autocorrect to ensure the descriptions remain natural and
1963+
accurate.
1964+
1965+
This is not classified as an unsafe autocorrect because it does not
1966+
affect code behavior, but manual review of changes is strongly
1967+
recommended.
1968+
19561969
[#examples-rspecexamplewording]
19571970
=== Examples
19581971

lib/rubocop/cop/rspec/example_wording.rb

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,19 @@ module RSpec
1010
#
1111
# @see http://betterspecs.org/#should
1212
#
13-
# The autocorrect is experimental - use with care! It can be configured
14-
# with CustomTransform (e.g. have => has) and IgnoredWords (e.g. only).
13+
# @safety
14+
# The autocorrect is experimental - use with care! It can be configured
15+
# with CustomTransform (e.g. have => has) and IgnoredWords (e.g. only).
16+
#
17+
# While the autocorrect will not break your code (it only modifies test
18+
# description strings, not the actual test logic), it may produce
19+
# grammatically incorrect English in some cases. Always review the diff
20+
# when using autocorrect to ensure the descriptions remain natural and
21+
# accurate.
22+
#
23+
# This is not classified as an unsafe autocorrect because it does not
24+
# affect code behavior, but manual review of changes is strongly
25+
# recommended.
1526
#
1627
# Use the DisallowedExamples setting to prevent unclear or insufficient
1728
# descriptions. Please note that this config will not be treated as

0 commit comments

Comments
 (0)