From 5ff6ad38b0c866d6a5fb4cf13b035092704cc5a0 Mon Sep 17 00:00:00 2001
From: Phil Pirozhkov <hello@fili.pp.ru>
Date: Sat, 20 Feb 2021 12:24:43 +0300
Subject: [PATCH] Clarify pending docs

---
 lib/rspec/core/pending.rb | 43 +++++++++++++++++++++++++++++----------
 1 file changed, 32 insertions(+), 11 deletions(-)

diff --git a/lib/rspec/core/pending.rb b/lib/rspec/core/pending.rb
index f04e3be3b7..5942ccd406 100644
--- a/lib/rspec/core/pending.rb
+++ b/lib/rspec/core/pending.rb
@@ -38,7 +38,7 @@ class PendingExampleFixedError < StandardError; end
       # @param message [String] optional message to add to the summary report.
       #
       # @example
-      #     describe "an example" do
+      #     describe "some behaviour" do
       #       # reported as "Pending: no reason given"
       #       it "is pending with no message" do
       #         pending
@@ -52,21 +52,42 @@ class PendingExampleFixedError < StandardError; end
       #       end
       #     end
       #
-      # @note `before(:example)` hooks are eval'd when you use the `pending`
-      #   method within an example. If you want to declare an example `pending`
-      #   and bypass the `before` hooks as well, you can pass `:pending => true`
-      #   to the `it` method:
+      # @example Alternatively, you can use the `pending` example alias method:
       #
-      #       it "does something", :pending => true do
+      #     describe "SomeClass" do
+      #       pending "does not implement something yet" do
       #         # ...
       #       end
+      #     end
       #
-      #   or pass `:pending => "something else getting finished"` to add a
-      #   message to the summary report:
+      #   or specify metadata on an example:
       #
-      #       it "does something", :pending => "something else getting finished" do
-      #         # ...
-      #       end
+      #     it "does this", :pending => "is not yet implemented" do
+      #        # ...
+      #     end
+      #
+      #   even without an explicit pending message:
+      #
+      #     it "does something", :pending do
+      #       # ...
+      #     end
+      #
+      # @note There is a difference between using `pending` inside the example
+      # body and `pending` example group alias/`pending` metadata. In the case
+      # when the failure is caused by the code in the `before` hook, the example
+      # would not be considered pending, as the example body wouldn't be reached.
+      # If you intend the failure in the `before` hook to be considered a part
+      # of the example, use the latter.
+      #
+      # @example Failure in `before` hook causes the example to fail
+      #     before { fail 'BOOM' }
+      #     it 'fails' do
+      #       pending 'this never gets executed'
+      #     end
+      #
+      #     pending 'is considered pending' do
+      #       not_implemented
+      #     end
       def pending(message=nil)
         current_example = RSpec.current_example