[Fix #5713] Explicitly test, and add documentation note, for behaviou…

…r of multiline comment blocks (#8798)

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]

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

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