From 2a35e984c84019aac5d2ab70385421af3e4fe100 Mon Sep 17 00:00:00 2001
From: Daniel Vandersluis <daniel.vandersluis@gmail.com>
Date: Sat, 26 Sep 2020 02:41:19 -0400
Subject: [PATCH] [Fix #5713] Explicitly test, and add documentation note, for
 behaviour of multiline comment blocks (#8798)

---
 docs/modules/ROOT/pages/cops_style.adoc           |  6 ++++++
 lib/rubocop/cop/style/comment_annotation.rb       |  6 ++++++
 spec/rubocop/cop/style/comment_annotation_spec.rb | 11 +++++++++++
 3 files changed, 23 insertions(+)

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