Merge pull request rspec#2681 from rspec/metadata-slightly-improve-co…

…de-and-docs

Some improvements to metadata docs

lib/rspec/core/configuration.rb

@@ -1350,6 +1350,12 @@ def exclusion_filter
       #       end
       #     end
       #
+      #     module PreferencesHelpers
+      #       def preferences(user, preferences = {})
+      #         # ...
+      #       end
+      #     end
+      #
       #     module UserHelpers
       #       def users(username)
       #         # ...
@@ -1358,12 +1364,17 @@ def exclusion_filter
       #
       #     RSpec.configure do |config|
       #       config.include(UserHelpers) # included in all groups
+      #
+      #       # included in examples with `:preferences` metadata
+      #       config.include(PreferenceHelpers, :preferences)
+      #
+      #       # included in examples with `:type => :request` metadata
       #       config.include(AuthenticationHelpers, :type => :request)
       #     end
       #
-      #     describe "edit profile", :type => :request do
+      #     describe "edit profile", :preferences, :type => :request do
       #       it "can be viewed by owning user" do
-      #         login_as users(:jdoe)
+      #         login_as preferences(users(:jdoe), :lang => 'es')
       #         get "/profiles/jdoe"
       #         assert_select ".username", :text => 'jdoe'
       #       end
@@ -1391,17 +1402,21 @@ def include(mod, *filters)
       #
       # @example
       #
-      #     RSpec.shared_context "example users" do
+      #     RSpec.shared_context "example admin user" do
       #       let(:admin_user) { create_user(:admin) }
+      #     end
+      #
+      #     RSpec.shared_context "example guest user" do
       #       let(:guest_user) { create_user(:guest) }
       #     end
       #
       #     RSpec.configure do |config|
-      #       config.include_context "example users", :type => :request
+      #       config.include_context "example guest user", :type => :request
+      #       config.include_context "example admin user", :admin, :type => :request
       #     end
       #
       #     RSpec.describe "The admin page", :type => :request do
-      #       it "can be viewed by admins" do
+      #       it "can be viewed by admins", :admin do
       #         login_with admin_user
       #         get "/admin"
       #         expect(response).to be_ok
@@ -1443,12 +1458,20 @@ def include_context(shared_group_name, *filters)
       #       end
       #     end
       #
+      #     module PermissionHelpers
+      #       def define_permissions
+      #         # ...
+      #       end
+      #     end
+      #
       #     RSpec.configure do |config|
       #       config.extend(UiHelpers, :type => :request)
+      #       config.extend(PermissionHelpers, :with_permissions, :type => :request)
       #     end
       #
-      #     describe "edit profile", :type => :request do
+      #     describe "edit profile", :with_permissions, :type => :request do
       #       run_in_browser
+      #       define_permissions
       #
       #       it "does stuff in the client" do
       #         # ...
@@ -1906,7 +1929,8 @@ def apply_derived_metadata_to(metadata)
       #
       # This method differs from {Hooks#before} in only one way: it supports
       # the `:suite` scope. Hooks with the `:suite` scope will be run once before
-      # the first example of the entire suite is executed.
+      # the first example of the entire suite is executed. Conditions passed along
+      # with `:suite` are effectively ignored.
       #
       # @see #prepend_before
       # @see #after
@@ -1935,7 +1959,8 @@ def before(scope=nil, *meta, &block)
       #
       # This method differs from {Hooks#prepend_before} in only one way: it supports
       # the `:suite` scope. Hooks with the `:suite` scope will be run once before
-      # the first example of the entire suite is executed.
+      # the first example of the entire suite is executed. Conditions passed along
+      # with `:suite` are effectively ignored.
       #
       # @see #before
       # @see #after
@@ -1959,7 +1984,8 @@ def prepend_before(scope=nil, *meta, &block)
       #
       # This method differs from {Hooks#after} in only one way: it supports
       # the `:suite` scope. Hooks with the `:suite` scope will be run once after
-      # the last example of the entire suite is executed.
+      # the last example of the entire suite is executed. Conditions passed along
+      # with `:suite` are effectively ignored.
       #
       # @see #append_after
       # @see #before
@@ -1988,7 +2014,8 @@ def after(scope=nil, *meta, &block)
       #
       # This method differs from {Hooks#append_after} in only one way: it supports
       # the `:suite` scope. Hooks with the `:suite` scope will be run once after
-      # the last example of the entire suite is executed.
+      # the last example of the entire suite is executed. Conditions passed along
+      # with `:suite` are effectively ignored.
       #
       # @see #append_after
       # @see #before

lib/rspec/core/example_group.rb

@@ -111,16 +111,14 @@ def described_class
       #   @overload $1
       #   @overload $1(&example_implementation)
       #     @param example_implementation [Block] The implementation of the example.
-      #   @overload $1(doc_string, *metadata_keys, metadata={})
+      #   @overload $1(doc_string, *metadata)
       #     @param doc_string [String] The example's doc string.
-      #     @param metadata [Hash] Metadata for the example.
-      #     @param metadata_keys [Array<Symbol>] Metadata tags for the example.
-      #       Will be transformed into hash entries with `true` values.
-      #   @overload $1(doc_string, *metadata_keys, metadata={}, &example_implementation)
+      #     @param metadata [Array<Symbol>, Hash] Metadata for the example.
+      #       Symbols will be transformed into hash entries with `true` values.
+      #   @overload $1(doc_string, *metadata, &example_implementation)
       #     @param doc_string [String] The example's doc string.
-      #     @param metadata [Hash] Metadata for the example.
-      #     @param metadata_keys [Array<Symbol>] Metadata tags for the example.
-      #       Will be transformed into hash entries with `true` values.
+      #     @param metadata [Array<Symbol>, Hash] Metadata for the example.
+      #       Symbols will be transformed into hash entries with `true` values.
       #     @param example_implementation [Block] The implementation of the example.
       #   @yield [Example] the example object
       #   @example
@@ -139,6 +137,11 @@ def described_class
       #     $1 "does something" do |ex|
       #       # ex is the Example object that contains metadata about the example
       #     end
+      #
+      #  @example
+      #     $1 "does something", :slow, :load_factor => 100 do
+      #     end
+      #
       def self.define_example_method(name, extra_options={})
         idempotently_define_singleton_method(name) do |*all_args, &block|
           desc, *args = *all_args
@@ -204,11 +207,10 @@ def self.define_example_method(name, extra_options={})
       #   @overload $1
       #   @overload $1(&example_group_definition)
       #     @param example_group_definition [Block] The definition of the example group.
-      #   @overload $1(doc_string, *metadata_keys, metadata={}, &example_implementation)
+      #   @overload $1(doc_string, *metadata, &example_implementation)
       #     @param doc_string [String] The group's doc string.
-      #     @param metadata [Hash] Metadata for the group.
-      #     @param metadata_keys [Array<Symbol>] Metadata tags for the group.
-      #       Will be transformed into hash entries with `true` values.
+      #     @param metadata [Array<Symbol>, Hash] Metadata for the group.
+      #       Symbols will be transformed into hash entries with `true` values.
       #     @param example_group_definition [Block] The definition of the example group.
       #
       #   Generates a subclass of this example group which inherits
@@ -223,12 +225,21 @@ def self.define_example_method(name, extra_options={})
       #         do_something_before
       #       end
       #
+      #       before(:example, :clean_env) do
+      #         env.clear!
+      #       end
+      #
       #       let(:thing) { Thing.new }
       #
       #       $1 "attribute (of something)" do
       #         # examples in the group get the before hook
       #         # declared above, and can access `thing`
       #       end
+      #
+      #       $1 "needs additional setup", :clean_env, :implementation => JSON do
+      #         # specifies that hooks with matching metadata
+      #         # should be be run additionally
+      #       end
       #     end
       #
       # @see DSL#describe

lib/rspec/core/hooks.rb

@@ -13,13 +13,14 @@ module Hooks
       # @overload before(scope, &block)
       #   @param scope [Symbol] `:example`, `:context`, or `:suite`
       #     (defaults to `:example`)
-      # @overload before(scope, conditions, &block)
+      # @overload before(scope, *conditions, &block)
       #   @param scope [Symbol] `:example`, `:context`, or `:suite`
       #     (defaults to `:example`)
-      #   @param conditions [Hash]
-      #     constrains this hook to examples matching these conditions e.g.
+      #   @param conditions [Array<Symbol>, Hash] constrains this hook to
+      #     examples matching these conditions e.g.
       #     `before(:example, :ui => true) { ... }` will only run with examples
-      #     or groups declared with `:ui => true`.
+      #     or groups declared with `:ui => true`. Symbols will be transformed
+      #     into hash entries with `true` values.
       # @overload before(conditions, &block)
       #   @param conditions [Hash]
       #     constrains this hook to examples matching these conditions e.g.
@@ -214,13 +215,14 @@ def prepend_before(*args, &block)
       # @overload after(scope, &block)
       #   @param scope [Symbol] `:example`, `:context`, or `:suite` (defaults to
       #     `:example`)
-      # @overload after(scope, conditions, &block)
+      # @overload after(scope, *conditions, &block)
       #   @param scope [Symbol] `:example`, `:context`, or `:suite` (defaults to
       #     `:example`)
-      #   @param conditions [Hash]
-      #     constrains this hook to examples matching these conditions e.g.
+      #   @param conditions [Array<Symbol>, Hash] constrains this hook to
+      #     examples matching these conditions e.g.
       #     `after(:example, :ui => true) { ... }` will only run with examples
-      #     or groups declared with `:ui => true`.
+      #     or groups declared with `:ui => true`. Symbols will be transformed
+      #     into hash entries with `true` values.
       # @overload after(conditions, &block)
       #   @param conditions [Hash]
       #     constrains this hook to examples matching these conditions e.g.
@@ -290,13 +292,15 @@ def append_after(*args, &block)
       #   @param scope [Symbol] `:example` (defaults to `:example`)
       #     present for syntax parity with `before` and `after`, but
       #     `:example`/`:each` is the only supported value.
-      # @overload around(scope, conditions, &block)
+      # @overload around(scope, *conditions, &block)
       #   @param scope [Symbol] `:example` (defaults to `:example`)
       #     present for syntax parity with `before` and `after`, but
       #     `:example`/`:each` is the only supported value.
-      #   @param conditions [Hash] constrains this hook to examples matching
-      #     these conditions e.g. `around(:example, :ui => true) { ... }` will
-      #     only run with examples or groups declared with `:ui => true`.
+      #   @param conditions [Array<Symbol>, Hash] constrains this hook to
+      #     examples matching these conditions e.g.
+      #     `around(:example, :ui => true) { ... }` will only run with examples
+      #     or groups declared with `:ui => true`. Symbols will be transformed
+      #     into hash entries with `true` values.
       # @overload around(conditions, &block)
       #   @param conditions [Hash] constrains this hook to examples matching
       #     these conditions e.g. `around(:example, :ui => true) { ... }` will