README.md in assert-2.10.1 vs README.md in assert-2.11.0

@@ -38,18 +38,82 @@
 
 ## What Assert is not
 
 * **Rspec**
 * **Unit/Functional/Integration/etc**: Assert is agnostic - you define whatever kinds of tests you like (one or more of the above) and assert runs them in context.
-* **Mock/Spec/BDD/Factories/etc**: Assert is the framework and there are a variety of 3rd party tools to do such things - feel free to use whatever you like.
+* **Mock/Spec/BDD/etc**: Assert is the framework and there are a variety of 3rd party tools to do such things - feel free to use whatever you like.
 
 ## Description
 
 Assert is a Test::Unit style testing framework.  This means you can write tests in Assert the same way you would with test-unit.
 
 In addition, Assert adds some helpers and syntax sugar to enhance the way tests are written. Most are taken from ideas in [Shoulda](https://github.com/thoughtbot/shoulda) and [Leftright](https://github.com/jordi/leftright/).  Assert uses class-based contexts so if you want to nest your contexts, use inheritance.
 
 **Note**: Assert is tested using itself.  The tests are a pretty good place to look for examples and usage patterns.
+
+## Defining tests
+
+TODO
+
+## Factory
+
+TODO
+
+## Stub
+
+```ruby
+myclass = Class.new do
+  def mymeth; 'meth'; end
+  def myval(val); val; end
+end
+myobj = myclass.new
+
+myobj.mymeth
+  # => 'meth'
+myobj.myval(123)
+  # => 123
+myobj.myval(456)
+  # => 456
+
+Assert.stub(myobj, :mymeth)
+myobj.mymeth
+  # => StubError: `mymeth` not stubbed.
+Assert.stub(myobj, :mymeth){ 'stub-meth' }
+myobj.mymeth
+  # => 'stub-meth'
+myobj.mymeth(123)
+  # => StubError: arity mismatch
+Assert.stub(myobj, :mymeth).with(123){ 'stub-meth' }
+  # => StubError: arity mismatch
+
+Assert.stub(myobj, :myval){ 'stub-meth' }
+  # => StubError: arity mismatch
+Assert.stub(myobj, :myval).with(123){ |val| val.to_s }
+myobj.myval
+  # => StubError: arity mismatch
+myobj.mymeth(123)
+  # => '123'
+myobj.mymeth(456)
+  # => StubError: `mymeth(456)` not stubbed.
+
+Assert.unstub(myobj, :mymeth)
+
+myobj.mymeth
+  # => 'meth'
+myobj.myval(123)
+  # => 123
+myobj.myval(456)
+  # => 456
+```
+
+Assert comes with a simple stubbing API - all it does is replace method calls.  In general it tries
+to be friendly and complain if stubbing doesn't match up with the object/method being stubbed:
+
+* each stub takes a block that is called in place of the method
+* complains if you stub a method that the object doesn't respond to
+* complains if you stub with an arity mismatch
+* no methods added to `Object`
+* stubs are auto-unstubbed on test teardown
 
 ## CLI
 
 ```sh
 $ assert --help