add matcher overview

features/README.markdown

@@ -6,14 +6,23 @@ rspec-expectations is used to set expectations in executable examples.
       end
     end
 
-## should and should_not
+## Basic structure
 
-rspec-expectations adds `should` and `should_not` to every object. Each of
-these can accept a matcher and, in most cases, an optional custom failure
-message (see [customized
-message](/rspec/rspec-expectations/v/2-3/customized-message)).
+The basic structure of an rspec expectation is:
 
-## Matchers
+    actual.should matcher(expected)
+    actual.should_not matcher(expected)
+
+## `should` and `should_not`
+
+`rspec-expectations` adds `should` and `should_not` to every object in
+the system. These methods each accept a matcher as an argument. This allows
+each matcher to work in a positive or negative mode:
+
+    5.should eq(5)
+    5.should_not eq(4)
+
+## What is a matcher?
 
 A Matcher is any object that responds to the following methods:
 
@@ -27,9 +36,9 @@ These methods are also part of the matcher protocol, but are optional:
     description
 
 RSpec ships with a number of [built-in
-matchers](/rspec/rspec-expectations/v/2-3/dir/built-in-matchers) and a DSL for
+matchers](/rspec/rspec-expectations/v/2-6-rc/dir/built-in-matchers) and a DSL for
 writing your own [custom
-matchers](/rspec/rspec-expectations/v/2-3/dir/custom-matchers).
+matchers](/rspec/rspec-expecations/v/2-6-rc/dir/custom-matchers).
 
 ## Issues
 

features/built_in_matchers/README.md

@@ -0,0 +1,73 @@
+## Object identity
+
+    actual.should equal(expected) # passes if actual.equal?(expected)
+
+## Object equivalence
+
+    actual.should == expected   # passes if actual == expected
+    actual.should eql(expected) # passes if actual.eql?(expected)
+
+## Optional APIs for identity/equivalence
+
+    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
+
+    actual.should =~ /expression/
+    actual.should match(/expression/)
+
+## Types/classes
+
+    actual.should be_instance_of(expected)
+    actual.should be_kind_of(expected)
+
+## Truthiness and existentialism
+
+    actual.should be_true  # passes if actual is anything but nil or false
+    actual.should be_false # passes if actual is nil or false
+    actual.should be_nil   # passes if actual is nil
+    actual.should be       # passes if actual is not nil
+
+## Expecting errors
+
+    expect { ... }.to raise_error
+    expect { ... }.to raise_error(ErrorClass)
+    expect { ... }.to raise_error("message")
+    expect { ... }.to raise_error(ErrorClass, "message")
+
+## Expecting throws
+
+    expect { ... }.to throw_symbol
+    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?
+
+### Example
+
+    [].should be_empty # passes because [].empty? returns true
+
+## Collection membership
+
+    actual.should include(expected)
+
+### Examples
+
+    [1,2,3].should include(1)
+    [1,2,3].should include(1, 2)
+    {:a => 'b'}.should include(:a => 'b')
+    "this string".should include("is str")