more improvments to RDoc for change matcher

History.markdown

@@ -1,5 +1,12 @@
 ## rspec-expectations release history (incomplete)
 
+### 2.4.0 / in development
+
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.3.0...master)
+
+* Enhancements
+  * improved RDoc for change matcher (Jo Liss)
+
 ### 2.3.0 / 2010-12-12
 
 [full changelog](http://github.com/rspec/rspec-expectations/compare/v2.2.1...v2.3.0)

lib/rspec/matchers/change.rb

@@ -123,16 +123,26 @@ def matches_max?
     end
 
     # :call-seq:
-    #   should change(receiver, message, &block)
-    #   should change(receiver, message, &block).by(value)
-    #   should change(receiver, message, &block).from(old).to(new)
-    #   should_not change(receiver, message, &block)
+    #   should change(receiver, message)
+    #   should change(receiver, message).by(value)
+    #   should change(receiver, message).from(old).to(new)
+    #   should_not change(receiver, message)
     #
-    # Allows you to specify that a Proc will cause some value to change.
+    #   should change {...}
+    #   should change {...}.by(value)
+    #   should change {...}.from(old).to(new)
+    #   should_not change {...}
+    #
+    # Applied to a proc, specifies that its execution will cause some value to
+    # change.
     #
     # You can either pass <tt>receiver</tt> and <tt>message</tt>, or a block,
     # but not both.
     #
+    # When passing a block, it must use the <tt>{ ... }</tt> format, not
+    # do/end, as <tt>{ ... }</tt> binds to the +change+ method, whereas do/end
+    # would errantly bind to the +should+ or +should_not+ method.
+    #
     # == Examples
     #
     #   lambda {
@@ -164,22 +174,15 @@ def matches_max?
     #     employee.develop_great_new_social_networking_app
     #   }.should change(employee, :title).from("Mail Clerk").to("CEO")
     #
-    # Evaluates <tt>receiver.message</tt> or <tt>block</tt> before and after
-    # it evaluates the c object (generated by the lambdas in the examples
-    # above).
-    #
-    # Then compares the values before and after the <tt>receiver.message</tt>
-    # and evaluates the difference compared to the expected difference.
-    #
-    # == WARNING
-    # <tt>should_not change</tt> only supports the form with no
-    # subsequent calls to <tt>by</tt>, <tt>by_at_least</tt>,
-    # <tt>by_at_most</tt>, <tt>to</tt> or <tt>from</tt>.
+    # == Notes
     #
-    # blocks passed to <tt>should</tt> <tt>change</tt> and <tt>should_not</tt>
-    # <tt>change</tt> must use the <tt>{}</tt> form (<tt>do/end</tt> is not
-    # supported).
+    # Evaluates <tt>receiver.message</tt> or <tt>block</tt> before and after it
+    # evaluates the proc object (generated by the lambdas in the examples
+    # above).
     #
+    # <tt>should_not change</tt> only supports the form with no subsequent
+    # calls to <tt>by</tt>, <tt>by_at_least</tt>, <tt>by_at_most</tt>,
+    # <tt>to</tt> or <tt>from</tt>.
     def change(receiver=nil, message=nil, &block)
       Matchers::Change.new(receiver, message, &block)
     end