Update docs for hooks specifying order of before/around/after

Author: JonRowe

features/hooks/around_hooks.feature

@@ -17,6 +17,9 @@ Feature: `around` hooks
   **WARNING:** Mock frameworks are set up and torn down within the context of
   running the example. You cannot interact with them directly in `around` hooks.
 
+  **WARNING:** `around` hooks will execute *after* any `before` hooks, and *before*
+  any `after` hooks regardless of the context they were defined in.
+
   Scenario: Use the example as a proc within the block passed to `around()`
     Given a file named "example_spec.rb" with:
       """ruby

features/hooks/before_and_after_hooks.feature

@@ -29,6 +29,9 @@ Feature: `before` and `after` hooks
 
   **WARNING:** Mocks are only supported in `before(:example)`.
 
+  **WARNING:** `around` hooks will execute *after* any `before` hooks, and *before*
+  any `after` hooks regardless of the context they were defined in.
+
   Note: the `:example` and `:context` scopes are also available as `:each` and
   `:all`, respectively. Use whichever you prefer.
 

lib/rspec/core/hooks.rb

@@ -60,7 +60,8 @@ module Hooks
       #     before(:example)  # Declared in the current group.
       #
       # If more than one `before` is declared within any one scope, they are run
-      # in the order in which they are declared.
+      # in the order in which they are declared. Any `around` hooks will execute
+      # later than any `before` hook regardless of scope.
       #
       # ### Conditions
       #
@@ -261,7 +262,8 @@ def prepend_before(*args, &block)
       #
       # This is the reverse of the order in which `before` hooks are run.
       # Similarly, if more than one `after` is declared within any one scope,
-      # they are run in reverse order of that in which they are declared.
+      # they are run in reverse order of that in which they are declared. Also
+      # `around` hooks will all have run before any after hooks are invoked.
       #
       # @note The `:example` and `:context` scopes are also available as
       #       `:each` and `:all`, respectively. Use whichever you prefer.
@@ -329,6 +331,12 @@ def append_after(*args, &block)
       #     around(:example) {|ex| Database.transaction(&ex)}
       #     around(:example) {|ex| FakeFS(&ex)}
       #
+      # ### Order
+      #
+      # All `around` hooks execute immediately surrounding an example, this means
+      # that all `before` hooks will have run and no `after` hooks will have run yet.
+      #
+      # They are not a synonym for `before`/`after`.
       def around(*args, &block)
         hooks.register :prepend, :around, *args, &block
       end