diff --git a/docs/modules/ROOT/pages/cops_style.adoc b/docs/modules/ROOT/pages/cops_style.adoc index 809b549461e..3d538d9a046 100644 --- a/docs/modules/ROOT/pages/cops_style.adoc +++ b/docs/modules/ROOT/pages/cops_style.adoc @@ -1576,6 +1576,12 @@ folders = %x(find . -type d).split This cop checks that comment annotation keywords are written according to guidelines. +NOTE: With a multiline comment block (where each line is only a +comment), only the first line will be able to register an offense, even +if an annotation keyword starts another line. This is done to prevent +incorrect registering of keywords (eg. `review`) inside a paragraph as an +annotation. + === Examples [source,ruby] diff --git a/lib/rubocop/cop/style/comment_annotation.rb b/lib/rubocop/cop/style/comment_annotation.rb index 0824d79514b..23f4ce630c9 100644 --- a/lib/rubocop/cop/style/comment_annotation.rb +++ b/lib/rubocop/cop/style/comment_annotation.rb @@ -6,6 +6,12 @@ module Style # This cop checks that comment annotation keywords are written according # to guidelines. # + # NOTE: With a multiline comment block (where each line is only a + # comment), only the first line will be able to register an offense, even + # if an annotation keyword starts another line. This is done to prevent + # incorrect registering of keywords (eg. `review`) inside a paragraph as an + # annotation. + # # @example # # bad # # TODO make better diff --git a/spec/rubocop/cop/style/comment_annotation_spec.rb b/spec/rubocop/cop/style/comment_annotation_spec.rb index 48cbd9c0849..5f2bd8171f4 100644 --- a/spec/rubocop/cop/style/comment_annotation_spec.rb +++ b/spec/rubocop/cop/style/comment_annotation_spec.rb @@ -133,4 +133,15 @@ class ToBeDone RUBY end end + + context 'multiline comment' do + it 'only registers an offense on the first line' do + expect_offense(<<~RUBY) + # TODO line 1 + ^^^^^ Annotation keywords like `TODO` should be all upper case, followed by a colon, and a space, then a note describing the problem. + # TODO line 2 + # TODO line 3 + RUBY + end + end end