doc updates

features/.nav

@@ -1,4 +1,5 @@
 - Upgrade.md
+- Changelog.md
 - customized_message.feature
 - diffing.feature
 - implicit_docstrings.feature

features/Changelog.md

@@ -1,6 +1,6 @@
 ### 2.6.0.rc2 / 2011-04-18
 
-[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.5.0...v2.6.1.rc2)
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.5.0...v2.6.0.rc2)
 
 * Enhancments
   * `change` matcher accepts Regexps (Robert Davis)

features/README.markdown

@@ -1,4 +1,4 @@
-rspec-expectations is used to set expectations in executable examples.
+rspec-expectations is used to define expected outcomes.
 
     describe Account do
       it "has a balance of zero when first created" do
@@ -35,10 +35,8 @@ These methods are also part of the matcher protocol, but are optional:
     failure_message_for_should_not
     description
 
-RSpec ships with a number of [built-in
-matchers](/rspec/rspec-expectations/v/2-6-rc/dir/built-in-matchers) and a DSL for
-writing your own [custom
-matchers](/rspec/rspec-expecations/v/2-6-rc/dir/custom-matchers).
+RSpec ships with a number of built-in matchers and a DSL for writing custom
+matchers.
 
 ## Issues
 

features/built_in_matchers/README.md

@@ -12,14 +12,15 @@
     actual.should eq(expected)  # passes if actual == expected
     actual.should be(expected)  # passes if actual.equal?(expected)
 
-## Near-equality (for floats)
-
-    actual.should be_within(delta).of(expected)
-
-## Regular expressions
+## Comparisons
 
+    actual.should be >  expected
+    actual.should be >= expected
+    actual.should be <= expected
+    actual.should be <  expected
     actual.should =~ /expression/
     actual.should match(/expression/)
+    actual.should be_within(delta).of(expected)
 
 ## Types/classes
 
@@ -46,13 +47,6 @@
     expect { ... }.to throw_symbol(:symbol)
     expect { ... }.to throw_symbol(:symbol, 'value')
 
-## Operator matchers
-
-    actual.should be >  expected
-    actual.should be >= expected
-    actual.should be <= expected
-    actual.should be <  expected
-
 ## Predicate matchers
 
     actual.should be_xxx # passes if actual.xxx?

features/built_in_matchers/be_within.feature

@@ -3,17 +3,17 @@ Feature: be_within matcher
   Normal equality expectations do not work well for floating point values.
   Consider this irb session:
 
-    > radius = 3
-      => 3 
-    > area_of_circle = radius * radius * Math::PI
-      => 28.2743338823081 
-    > area_of_circle == 28.2743338823081
-      => false 
+      > radius = 3
+        => 3 
+      > area_of_circle = radius * radius * Math::PI
+        => 28.2743338823081 
+      > area_of_circle == 28.2743338823081
+        => false 
 
   Instead, you should use the be_within matcher to check that the value
   is within a delta of your expected value:
 
-    area_of_circle.should be_within(0.1).of(28.3)
+      area_of_circle.should be_within(0.1).of(28.3)
 
   Note that the difference between the actual and expected values must be
   smaller than your delta; if it is equal, the matcher will fail.

features/built_in_matchers/equality.feature

@@ -2,24 +2,27 @@ Feature: equality matchers
 
   Ruby exposes several different methods for handling equality:
 
-    a.equal?(b) # object identity - a and b refer to the same object
-    a.eql?(b)   # object equivalence - a and b have the same value
-    a == b      # object equivalence - a and b have the same value with type conversions
+      a.equal?(b) # object identity - a and b refer to the same object
+      a.eql?(b)   # object equivalence - a and b have the same value
+      a == b      # object equivalence - a and b have the same value with type conversions
 
   Note that these descriptions are guidelines but are not forced by the
   language. Any object can implement any of these methods with its own
   semantics.
 
   rspec-expectations ships with matchers that align with each of these methods:
 
-    a.should equal(b) # passes if a.equal?(b)
-    a.should eql(b)   # passes if a.eql?(b)
-    a.should == b     # passes if a == b
+      a.should equal(b) # passes if a.equal?(b)
+      a.should eql(b)   # passes if a.eql?(b)
+      a.should == b     # passes if a == b
 
   It also ships with two matchers that have more of a DSL feel to them:
 
-    a.should be(b) # passes if a.equal?(b)
-    a.should eq(b) # passes if a == b
+      a.should be(b) # passes if a.equal?(b)
+      a.should eq(b) # passes if a == b
+
+  These are a useful pair if you wish to avoid the warning that Ruby emits on
+  `a.should == b`
 
   Scenario: compare using eq (==)
     Given a file named "compare_using_eq.rb" with:

features/built_in_matchers/exist.feature

@@ -5,7 +5,7 @@ Feature: exist matcher
 
     obj.should exist # passes if obj.exist? or obj.exists?
 
-  Scenario Outline: basic usage
+  Scenario: basic usage
     Given a file named "exist_matcher_spec.rb" with:
       """
       class Planet
@@ -19,31 +19,25 @@ Feature: exist matcher
           "<Planet: #{name}>"
         end
 
-        def <predicate_method>
+        def exist? # also works with exists?
           %w[Mercury Venus Earth Mars Jupiter Saturn Uranus Neptune].include?(name)
         end
       end
 
       describe "Earth" do
-        subject { Planet.new("Earth") }
-        it { should exist }
-        it { should_not exist } # deliberate failure
+        let(:earth) { Planet.new("Earth") }
+        specify { earth.should exist }
+        specify { earth.should_not exist } # deliberate failure
       end
 
       describe "Tatooine" do
-        subject { Planet.new("Tatooine") }
-        it { should_not exist }
-        it { should exist } # deliberate failure
+        let(:tatooine) { Planet.new("Tatooine") }
+        it { tatooine.should exist } # deliberate failure
+        it { tatooine.should_not exist }
       end
       """
     When I run `rspec exist_matcher_spec.rb`
     Then the output should contain all of these:
       | 4 examples, 2 failures                |
       | expected <Planet: Earth> not to exist |
       | expected <Planet: Tatooine> to exist  |
-
-    Examples:
-      | predicate_method |
-      | exist?           |
-      | exists?          |
-

features/built_in_matchers/predicates.feature

@@ -2,36 +2,36 @@ Feature: predicate matchers
 
   Ruby objects commonly provide predicate methods:
 
-    * 7.zero?                  # => false
-    * 0.zero?                  # => true
-    * [1].empty?               # => false
-    * [].empty?                # => true
-    * { :a => 5 }.has_key?(:b) # => false
-    * { :b => 5 }.has_key?(:b) # => true
+      7.zero?                  # => false
+      0.zero?                  # => true
+      [1].empty?               # => false
+      [].empty?                # => true
+      { :a => 5 }.has_key?(:b) # => false
+      { :b => 5 }.has_key?(:b) # => true
 
   You could use a basic equality matcher to set expectations on these:
 
-    7.zero?.should == true # fails with "expected true, got false (using ==)"
+      7.zero?.should == true # fails with "expected true, got false (using ==)"
 
   ...but RSpec provides dynamic predicate matchers that are more readable and
   provide better failure output.
 
   For any predicate method, RSpec gives you a corresponding matcher.  Simply
   prefix the method with "be_" and remove the question mark.  Examples:
 
-    * 7.should_not be_zero       # calls 7.zero?
-    * [].should be_empty         # calls [].empty?
-    * x.should be_multiple_of(3) # calls x.multiple_of?(3)
+      7.should_not be_zero       # calls 7.zero?
+      [].should be_empty         # calls [].empty?
+      x.should be_multiple_of(3) # calls x.multiple_of?(3)
 
   Alternately, for a predicate method that begins with "has_" like Hash#has_key?,
   RSpec allows you to use an alternate form since "be_has_key" makes no sense.
 
-    * hash.should have_key(:foo)       # calls hash.has_key?(:foo)
-    * array.should_not have_odd_values # calls array.has_odd_values?
+      hash.should have_key(:foo)       # calls hash.has_key?(:foo)
+      array.should_not have_odd_values # calls array.has_odd_values?
 
   In either case, RSpec provides nice, clear error messages, such as:
 
-    expected zero? to return true, got false
+      expected zero? to return true, got false
 
   Any arguments passed to the matcher will be passed on to the predicate method.