Document aggregate_failures behavior in MultipleExpectations cop

Rspec/MultipleExpectations supports :aggregate_failures by simply ignoring
any blocks enclosed in them. The only issue is that they don't really
appear in any of the docs so the behavior is mostly hidden. This update
merely adds two inline examples to RSpec/MultipleExpectations to allow
for greater discoverability.

Author: edgibbs

CHANGELOG.md

@@ -7,6 +7,7 @@
 * Add new `RSpec/Capybara/SpecificMatcher` cop. ([@ydah][])
 * Fixed false offense detection in `FactoryBot/CreateList` when a n.times block is including method calls in the factory create arguments. ([@ngouy][])
 * Fix error in `RSpec/RSpec/FactoryBot/CreateList` cop for empty block. ([@tejasbubane][])
+* Update `RSpec/MultipleExpectations` cop documentation with examples of aggregate_failures use. ([@edgibbs][])
 
 ## 2.11.1 (2022-05-18)
 
@@ -702,3 +703,4 @@ Compatibility release so users can upgrade RuboCop to 0.51.0. No new features.
 [@luke-hill]: https://github.com/luke-hill
 [@johnny-miyake]: https://github.com/johnny-miyake
 [@ngouy]: https://github.com/ngouy
+[@edgibbs]: https://github.com/edgibbs

docs/modules/ROOT/pages/cops_rspec.adoc

@@ -2837,6 +2837,32 @@ describe UserCreator do
 end
 ----
 
+==== `aggregate_failures: true` (default)
+
+[source,ruby]
+----
+# good - the cop ignores when RSpec aggregates failures
+ describe UserCreator do
+   it 'builds a user', :aggregate_failures do
+     expect(user.name).to eq("John")
+     expect(user.age).to eq(22)
+   end
+ end
+----
+
+==== `aggregate_failures: false`
+
+[source,ruby]
+----
+# Detected as an offense
+ describe UserCreator do
+   it 'builds a user', aggregate_failures: false do
+     expect(user.name).to eq("John")
+     expect(user.age).to eq(22)
+   end
+ end
+----
+
 ==== configuration
 
 [source,ruby]

lib/rubocop/cop/rspec/multiple_expectations.rb

@@ -31,6 +31,26 @@ module RSpec
       #     end
       #   end
       #
+      # @example `aggregate_failures: true` (default)
+      #
+      #  # good - the cop ignores when RSpec aggregates failures
+      #   describe UserCreator do
+      #     it 'builds a user', :aggregate_failures do
+      #       expect(user.name).to eq("John")
+      #       expect(user.age).to eq(22)
+      #     end
+      #   end
+      #
+      # @example `aggregate_failures: false`
+      #
+      #  # Detected as an offense
+      #   describe UserCreator do
+      #     it 'builds a user', aggregate_failures: false do
+      #       expect(user.name).to eq("John")
+      #       expect(user.age).to eq(22)
+      #     end
+      #   end
+      #
       # @example configuration
       #
       #   # .rubocop.yml