Use RSpec module on describe calls in docs. (#2571)

peagha · JonRowe · commit 58f38210492c · 2018-10-13T09:15:07.000+01:00
diff --git a/features/README.md b/features/README.md
@@ -1,6 +1,6 @@
 rspec-core provides the structure for RSpec code examples:
 
-    describe Account do
+    RSpec.describe Account do
       it "has a balance of zero when first opened" do
         # example code goes here - for more on the
         # code inside the examples, see rspec-expectations
diff --git a/lib/rspec/core/configuration.rb b/lib/rspec/core/configuration.rb
@@ -1106,15 +1106,15 @@ def spec_files_with_failures
       #
       #   # This lets you do this:
       #
-      #   describe Thing do
+      #   RSpec.describe Thing do
       #     pending "does something" do
       #       thing = Thing.new
       #     end
       #   end
       #
       #   # ... which is the equivalent of
       #
-      #   describe Thing do
+      #   RSpec.describe Thing do
       #     it "does something", :pending => true do
       #       thing = Thing.new
       #     end
@@ -1167,7 +1167,7 @@ def alias_example_group_to(new_name, *args)
       #
       #   # allows the user to include a shared example group like:
       #
-      #   describe Entity do
+      #   RSpec.describe Entity do
       #     it_has_behavior 'sortability' do
       #       let(:sortable) { Entity.new }
       #     end
@@ -1718,7 +1718,7 @@ def raise_on_warning=(value)
       #     rspec.expose_current_running_example_as :example
       #   end
       #
-      #   describe MyClass do
+      #   RSpec.describe MyClass do
       #     before do
       #       # `example` can be used here because of the above config.
       #       do_something if example.metadata[:type] == "foo"
diff --git a/lib/rspec/core/example_group.rb b/lib/rspec/core/example_group.rb
@@ -7,7 +7,7 @@ module Core
     # ExampleGroup and {Example} are the main structural elements of
     # rspec-core. Consider this example:
     #
-    #     describe Thing do
+    #     RSpec.describe Thing do
     #       it "does something" do
     #       end
     #     end
@@ -90,7 +90,7 @@ def self.description
       # Returns the class or module passed to the `describe` method (or alias).
       # Returns nil if the subject is not a class or module.
       # @example
-      #     describe Thing do
+      #     RSpec.describe Thing do
       #       it "does something" do
       #         described_class == Thing
       #       end
diff --git a/lib/rspec/core/hooks.rb b/lib/rspec/core/hooks.rb
@@ -74,11 +74,11 @@ module Hooks
       #       end
       #     end
       #
-      #     describe Something, :authorized => true do
+      #     RSpec.describe Something, :authorized => true do
       #       # The before hook will run in before each example in this group.
       #     end
       #
-      #     describe SomethingElse do
+      #     RSpec.describe SomethingElse do
       #       it "does something", :authorized => true do
       #         # The before hook will run before this example.
       #       end
@@ -159,7 +159,7 @@ module Hooks
       #
       # @example before(:example) declared in an {ExampleGroup}
       #
-      #     describe Thing do
+      #     RSpec.describe Thing do
       #       before(:example) do
       #         @thing = Thing.new
       #       end
@@ -171,7 +171,7 @@ module Hooks
       #
       # @example before(:context) declared in an {ExampleGroup}
       #
-      #     describe Parser do
+      #     RSpec.describe Parser do
       #       before(:context) do
       #         File.open(file_to_parse, 'w') do |f|
       #           f.write <<-CONTENT
diff --git a/lib/rspec/core/memoized_helpers.rb b/lib/rspec/core/memoized_helpers.rb
@@ -10,7 +10,7 @@ module MemoizedHelpers
       # @note `subject` was contributed by Joe Ferris to support the one-liner
       #   syntax embraced by shoulda matchers:
       #
-      #       describe Widget do
+      #       RSpec.describe Widget do
       #         it { is_expected.to validate_presence_of(:name) }
       #         # or
       #         it { should validate_presence_of(:name) }
@@ -23,7 +23,7 @@ module MemoizedHelpers
       # @example
       #
       #   # Explicit declaration of subject.
-      #   describe Person do
+      #   RSpec.describe Person do
       #     subject { Person.new(:birthdate => 19.years.ago) }
       #     it "should be eligible to vote" do
       #       subject.should be_eligible_to_vote
@@ -32,15 +32,15 @@ module MemoizedHelpers
       #   end
       #
       #   # Implicit subject => { Person.new }.
-      #   describe Person do
+      #   RSpec.describe Person do
       #     it "should be eligible to vote" do
       #       subject.should be_eligible_to_vote
       #       # ^ ^ explicit reference to subject not recommended
       #     end
       #   end
       #
       #   # One-liner syntax - expectation is set on the subject.
-      #   describe Person do
+      #   RSpec.describe Person do
       #     it { is_expected.to be_eligible_to_vote }
       #     # or
       #     it { should be_eligible_to_vote }
@@ -67,7 +67,7 @@ def subject
       #
       # @example
       #
-      #   describe Person do
+      #   RSpec.describe Person do
       #     it { should be_eligible_to_vote }
       #   end
       #
@@ -86,7 +86,7 @@ def should(matcher=nil, message=nil)
       #
       # @example
       #
-      #   describe Person do
+      #   RSpec.describe Person do
       #     it { should_not be_eligible_to_vote }
       #   end
       #
@@ -270,7 +270,7 @@ module ClassMethods
         #
         # @example
         #
-        #   describe Thing do
+        #   RSpec.describe Thing do
         #     let(:thing) { Thing.new }
         #
         #     it "does something" do
@@ -323,7 +323,7 @@ def let(name, &block)
         #     end
         #   end
         #
-        #   describe Thing do
+        #   RSpec.describe Thing do
         #     after(:example) { Thing.reset_count }
         #
         #     context "using let" do
@@ -379,13 +379,13 @@ def let!(name, &block)
         #
         # @example
         #
-        #   describe CheckingAccount, "with $50" do
+        #   RSpec.describe CheckingAccount, "with $50" do
         #     subject { CheckingAccount.new(Money.new(50, :USD)) }
         #     it { is_expected.to have_a_balance_of(Money.new(50, :USD)) }
         #     it { is_expected.not_to be_overdrawn }
         #   end
         #
-        #   describe CheckingAccount, "with a non-zero starting balance" do
+        #   RSpec.describe CheckingAccount, "with a non-zero starting balance" do
         #     subject(:account) { CheckingAccount.new(Money.new(50, :USD)) }
         #     it { is_expected.not_to be_overdrawn }
         #     it "has a balance equal to the starting balance" do
@@ -433,7 +433,7 @@ def subject(name=nil, &block)
         #     end
         #   end
         #
-        #   describe Thing do
+        #   RSpec.describe Thing do
         #     after(:example) { Thing.reset_count }
         #
         #     context "using subject" do
diff --git a/lib/rspec/core/metadata.rb b/lib/rspec/core/metadata.rb
@@ -7,7 +7,7 @@ module Core
     # In addition to metadata that is used internally, this also stores
     # user-supplied metadata, e.g.
     #
-    #     describe Something, :type => :ui do
+    #     RSpec.describe Something, :type => :ui do
     #       it "does something", :slow => true do
     #         # ...
     #       end
diff --git a/lib/rspec/core/shared_example_group.rb b/lib/rspec/core/shared_example_group.rb
@@ -76,7 +76,7 @@ module SharedExampleGroup
       #     end
       #   end
       #
-      #   describe Account do
+      #   RSpec.describe Account do
       #     it_behaves_like "auditable" do
       #       let(:auditable) { Account.new }
       #     end

Original file line number	Diff line number	Diff line change
`@@ -1106,15 +1106,15 @@ def spec_files_with_failures`
`1106`	`1106`	`#`
`1107`	`1107`	`# # This lets you do this:`
`1108`	`1108`	`#`
`1109`		`- # describe Thing do`
	`1109`	`+ # RSpec.describe Thing do`
`1110`	`1110`	`# pending "does something" do`
`1111`	`1111`	`# thing = Thing.new`
`1112`	`1112`	`# end`
`1113`	`1113`	`# end`
`1114`	`1114`	`#`
`1115`	`1115`	`# # ... which is the equivalent of`
`1116`	`1116`	`#`
`1117`		`- # describe Thing do`
	`1117`	`+ # RSpec.describe Thing do`
`1118`	`1118`	`# it "does something", :pending => true do`
`1119`	`1119`	`# thing = Thing.new`
`1120`	`1120`	`# end`
`@@ -1167,7 +1167,7 @@ def alias_example_group_to(new_name, *args)`
`1167`	`1167`	`#`
`1168`	`1168`	`# # allows the user to include a shared example group like:`
`1169`	`1169`	`#`
`1170`		`- # describe Entity do`
	`1170`	`+ # RSpec.describe Entity do`
`1171`	`1171`	`# it_has_behavior 'sortability' do`
`1172`	`1172`	`# let(:sortable) { Entity.new }`
`1173`	`1173`	`# end`
`@@ -1718,7 +1718,7 @@ def raise_on_warning=(value)`
`1718`	`1718`	`# rspec.expose_current_running_example_as :example`
`1719`	`1719`	`# end`
`1720`	`1720`	`#`
`1721`		`- # describe MyClass do`
	`1721`	`+ # RSpec.describe MyClass do`
`1722`	`1722`	`# before do`
`1723`	`1723`	# # `example` can be used here because of the above config.
`1724`	`1724`	`# do_something if example.metadata[:type] == "foo"`
Original file line number	Diff line number	Diff line change
`@@ -74,11 +74,11 @@ module Hooks`
`74`	`74`	`# end`
`75`	`75`	`# end`
`76`	`76`	`#`
`77`		`- # describe Something, :authorized => true do`
	`77`	`+ # RSpec.describe Something, :authorized => true do`
`78`	`78`	`# # The before hook will run in before each example in this group.`
`79`	`79`	`# end`
`80`	`80`	`#`
`81`		`- # describe SomethingElse do`
	`81`	`+ # RSpec.describe SomethingElse do`
`82`	`82`	`# it "does something", :authorized => true do`
`83`	`83`	`# # The before hook will run before this example.`
`84`	`84`	`# end`
`@@ -159,7 +159,7 @@ module Hooks`
`159`	`159`	`#`
`160`	`160`	`# @example before(:example) declared in an {ExampleGroup}`
`161`	`161`	`#`
`162`		`- # describe Thing do`
	`162`	`+ # RSpec.describe Thing do`
`163`	`163`	`# before(:example) do`
`164`	`164`	`# @thing = Thing.new`
`165`	`165`	`# end`
`@@ -171,7 +171,7 @@ module Hooks`
`171`	`171`	`#`
`172`	`172`	`# @example before(:context) declared in an {ExampleGroup}`
`173`	`173`	`#`
`174`		`- # describe Parser do`
	`174`	`+ # RSpec.describe Parser do`
`175`	`175`	`# before(:context) do`
`176`	`176`	`# File.open(file_to_parse, 'w') do \|f\|`
`177`	`177`	`# f.write <<-CONTENT`
Original file line number	Diff line number	Diff line change
`@@ -10,7 +10,7 @@ module MemoizedHelpers`
`10`	`10`	# @note `subject` was contributed by Joe Ferris to support the one-liner
`11`	`11`	`# syntax embraced by shoulda matchers:`
`12`	`12`	`#`
`13`		`- # describe Widget do`
	`13`	`+ # RSpec.describe Widget do`
`14`	`14`	`# it { is_expected.to validate_presence_of(:name) }`
`15`	`15`	`# # or`
`16`	`16`	`# it { should validate_presence_of(:name) }`
`@@ -23,7 +23,7 @@ module MemoizedHelpers`
`23`	`23`	`# @example`
`24`	`24`	`#`
`25`	`25`	`# # Explicit declaration of subject.`
`26`		`- # describe Person do`
	`26`	`+ # RSpec.describe Person do`
`27`	`27`	`# subject { Person.new(:birthdate => 19.years.ago) }`
`28`	`28`	`# it "should be eligible to vote" do`
`29`	`29`	`# subject.should be_eligible_to_vote`
`@@ -32,15 +32,15 @@ module MemoizedHelpers`
`32`	`32`	`# end`
`33`	`33`	`#`
`34`	`34`	`# # Implicit subject => { Person.new }.`
`35`		`- # describe Person do`
	`35`	`+ # RSpec.describe Person do`
`36`	`36`	`# it "should be eligible to vote" do`
`37`	`37`	`# subject.should be_eligible_to_vote`
`38`	`38`	`# # ^ ^ explicit reference to subject not recommended`
`39`	`39`	`# end`
`40`	`40`	`# end`
`41`	`41`	`#`
`42`	`42`	`# # One-liner syntax - expectation is set on the subject.`
`43`		`- # describe Person do`
	`43`	`+ # RSpec.describe Person do`
`44`	`44`	`# it { is_expected.to be_eligible_to_vote }`
`45`	`45`	`# # or`
`46`	`46`	`# it { should be_eligible_to_vote }`
`@@ -67,7 +67,7 @@ def subject`
`67`	`67`	`#`
`68`	`68`	`# @example`
`69`	`69`	`#`
`70`		`- # describe Person do`
	`70`	`+ # RSpec.describe Person do`
`71`	`71`	`# it { should be_eligible_to_vote }`
`72`	`72`	`# end`
`73`	`73`	`#`
`@@ -86,7 +86,7 @@ def should(matcher=nil, message=nil)`
`86`	`86`	`#`
`87`	`87`	`# @example`
`88`	`88`	`#`
`89`		`- # describe Person do`
	`89`	`+ # RSpec.describe Person do`
`90`	`90`	`# it { should_not be_eligible_to_vote }`
`91`	`91`	`# end`
`92`	`92`	`#`
`@@ -270,7 +270,7 @@ module ClassMethods`
`270`	`270`	`#`
`271`	`271`	`# @example`
`272`	`272`	`#`
`273`		`- # describe Thing do`
	`273`	`+ # RSpec.describe Thing do`
`274`	`274`	`# let(:thing) { Thing.new }`
`275`	`275`	`#`
`276`	`276`	`# it "does something" do`
`@@ -323,7 +323,7 @@ def let(name, &block)`
`323`	`323`	`# end`
`324`	`324`	`# end`
`325`	`325`	`#`
`326`		`- # describe Thing do`
	`326`	`+ # RSpec.describe Thing do`
`327`	`327`	`# after(:example) { Thing.reset_count }`
`328`	`328`	`#`
`329`	`329`	`# context "using let" do`
`@@ -379,13 +379,13 @@ def let!(name, &block)`
`379`	`379`	`#`
`380`	`380`	`# @example`
`381`	`381`	`#`
`382`		`- # describe CheckingAccount, "with $50" do`
	`382`	`+ # RSpec.describe CheckingAccount, "with $50" do`
`383`	`383`	`# subject { CheckingAccount.new(Money.new(50, :USD)) }`
`384`	`384`	`# it { is_expected.to have_a_balance_of(Money.new(50, :USD)) }`
`385`	`385`	`# it { is_expected.not_to be_overdrawn }`
`386`	`386`	`# end`
`387`	`387`	`#`
`388`		`- # describe CheckingAccount, "with a non-zero starting balance" do`
	`388`	`+ # RSpec.describe CheckingAccount, "with a non-zero starting balance" do`
`389`	`389`	`# subject(:account) { CheckingAccount.new(Money.new(50, :USD)) }`
`390`	`390`	`# it { is_expected.not_to be_overdrawn }`
`391`	`391`	`# it "has a balance equal to the starting balance" do`
`@@ -433,7 +433,7 @@ def subject(name=nil, &block)`
`433`	`433`	`# end`
`434`	`434`	`# end`
`435`	`435`	`#`
`436`		`- # describe Thing do`
	`436`	`+ # RSpec.describe Thing do`
`437`	`437`	`# after(:example) { Thing.reset_count }`
`438`	`438`	`#`
`439`	`439`	`# context "using subject" do`
Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,7 @@ module Core`
`7`	`7`	`# In addition to metadata that is used internally, this also stores`
`8`	`8`	`# user-supplied metadata, e.g.`
`9`	`9`	`#`
`10`		`- # describe Something, :type => :ui do`
	`10`	`+ # RSpec.describe Something, :type => :ui do`
`11`	`11`	`# it "does something", :slow => true do`
`12`	`12`	`# # ...`
`13`	`13`	`# end`
Original file line number	Diff line number	Diff line change
`@@ -76,7 +76,7 @@ module SharedExampleGroup`
`76`	`76`	`# end`
`77`	`77`	`# end`
`78`	`78`	`#`
`79`		`- # describe Account do`
	`79`	`+ # RSpec.describe Account do`
`80`	`80`	`# it_behaves_like "auditable" do`
`81`	`81`	`# let(:auditable) { Account.new }`
`82`	`82`	`# end`