fixup! Revert doc changes for pending.rb

Author: pirj

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 "some behaviour" do
+      #     describe "an example" do
       #       # reported as "Pending: no reason given"
       #       it "is pending with no message" do
       #         pending
@@ -52,42 +52,21 @@ class PendingExampleFixedError < StandardError; end
       #       end
       #     end
       #
-      # @example Alternatively, you can use the `pending` example alias method:
+      # @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:
       #
-      #     describe "SomeClass" do
-      #       pending "does not implement something yet" do
+      #       it "does something", :pending => true do
       #         # ...
       #       end
-      #     end
-      #
-      #   or specify metadata on an example:
-      #
-      #     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
+      #   or pass `:pending => "something else getting finished"` to add a
+      #   message to the summary report:
       #
-      #     pending 'is considered pending' do
-      #       not_implemented
-      #     end
+      #       it "does something", :pending => "something else getting finished" do
+      #         # ...
+      #       end
       def pending(message=nil)
         current_example = RSpec.current_example