Move multi-line comments with the code they're 'attached' to

Co-authored-by: Bevan J. Kay <email@bevankay.me>

Library/Homebrew/rubocops/cask/array_alphabetization.rb

@@ -38,15 +38,10 @@ module RuboCop
         end
 
         def sort_array(source)
-          # Combine each comment with the line below it so that they remain connected to the line they comment
+          # Combine each comment with the line(s) below so that they remain in the same relative location
           combined_source = source.each_with_index.map do |line, index|
-            if line.strip.start_with?("#") && index < source.length - 1
+            next if line.strip.start_with?("#")
-              "#{line}\n#{source[index + 1]}"
+            next recursively_find_comments(source, index, line)
-            elsif source[index - 1]&.strip&.start_with?("#")
-              nil
-            else
-              line
-            end
           end.compact
 
           # Separate the lines into those that should be sorted and those that should not
@@ -63,6 +58,14 @@ module RuboCop
           # Merge the sorted lines and the unsorted lines, preserving the original positions of the unsorted lines
           combined_source.map { |line| to_keep.include?(line) ? line : to_sort.shift }
         end
+
+        def recursively_find_comments(source, index, line)
+          if source[index - 1].strip.start_with?("#")
+            return recursively_find_comments(source, index - 1, "#{source[index - 1]}\n#{line}")
+          end
+
+          line
+        end
       end
     end
   end

Library/Homebrew/test/rubocops/cask/array_alphabetization_spec.rb

@@ -146,6 +146,9 @@ describe RuboCop::Cop::Cask::ArrayAlphabetization, :config do
                    ^ The array elements should be ordered alphabetically
           # comment related to foo
           "~/Library/Application Support/Foo",
+          # a really long comment related to Zoo
+          # and the Zoo comment continues
+          "~/Library/Application Support/Zoo",
           "~/Library/Application Support/Bar",
           "~/Library/Application Support/Baz", # in-line comment
         ]
@@ -161,6 +164,9 @@ describe RuboCop::Cop::Cask::ArrayAlphabetization, :config do
           "~/Library/Application Support/Baz", # in-line comment
           # comment related to foo
           "~/Library/Application Support/Foo",
+          # a really long comment related to Zoo
+          # and the Zoo comment continues
+          "~/Library/Application Support/Zoo",
         ]
       end
     CASK