Rewrite YARD docs in terms of expect rather than should.

lib/rspec/expectations.rb

@@ -11,28 +11,37 @@
 require 'rspec/expectations/diff_presenter'
 
 module RSpec
-  # RSpec::Expectations adds two instance methods to every object:
+  # RSpec::Expectations provides a simple, readable API to express
+  # the expected outcomes in a code example. To express an expected
+  # outcome, wrap an object or block in `expect`, call `to` or `to_not`
+  # (aliased as `not_to`) and pass it a matcher object:
   #
-  #     should(matcher=nil)
-  #     should_not(matcher=nil)
+  #     expect(order.total).to eq(Money.new(5.55, :USD))
+  #     expect(list).to include(user)
+  #     expect(message).not_to match(/foo/)
+  #     expect { do_something }.to raise_error
   #
-  # Both methods take an optional matcher object (See
-  # [RSpec::Matchers](../RSpec/Matchers)).  When `should` is invoked with a
-  # matcher, it turns around and calls `matcher.matches?(self)`.  For example,
+  # The last form (the block form) is needed to match against ruby constructs
+  # that are not objects, but can only be observed when executing a block
+  # of code. This includes raising errors, throwing symbols, yielding,
+  # and changing values.
+  #
+  # When `expect(...).to` is invoked with a matcher, it turns around
+  # and calls `matcher.matches?(<object wrapped by expect>)`.  For example,
   # in the expression:
   #
-  #     order.total.should eq(Money.new(5.55, :USD))
+  #     expect(order.total).to eq(Money.new(5.55, :USD))
   #
-  # the `should` method invokes the equivalent of `eq.matches?(order.total)`. If
-  # `matches?` returns true, the expectation is met and execution continues. If
-  # `false`, then the spec fails with the message returned by
-  # `eq.failure_message`.
+  # ...`eq(Money.new(5.55, :USD))` returns a matcher object, and it results
+  # in the equivalent of `eq.matches?(order.total)`. If `matches?` returns
+  # `true`, the expectation is met and execution continues. If `false`, then
+  # the spec fails with the message returned by `eq.failure_message`.
   #
   # Given the expression:
   #
-  #     order.entries.should_not include(entry)
+  #     expet(order.entries).not_to include(entry)
   #
-  # the `should_not` method invokes the equivalent of
+  # ...the `not_to` method (also available as `to_not`) invokes the equivalent of
   # `include.matches?(order.entries)`, but it interprets `false` as success, and
   # `true` as a failure, using the message generated by
   # `eq.failure_message_when_negated`.