Permalink
Browse files

doc: updates for yard

  • Loading branch information...
1 parent 2c55b13 commit ba6456d9ce85bbe0bdd24e387d42cb353e439136 @dchelimsky dchelimsky committed Jun 14, 2011
Showing with 141 additions and 167 deletions.
  1. +3 −0 .yardopts
  2. +2 −0 lib/rspec/expectations/extensions/array.rb
  3. +18 −44 lib/rspec/expectations/extensions/kernel.rb
  4. +76 −72 lib/rspec/matchers.rb
  5. +42 −51 lib/rspec/matchers/be.rb
View
3 .yardopts
@@ -0,0 +1,3 @@
+--no-document
+--no-private
+--exclude features
View
2 lib/rspec/expectations/extensions/array.rb
@@ -1,5 +1,7 @@
+# @private
class Array
unless public_instance_methods.map {|m| m.to_s}.include?('none?')
+ # Supports +none?+ on early patch levels of Ruby 1.8.6
def none?(&block)
!any?(&block)
end
View
62 lib/rspec/expectations/extensions/kernel.rb
@@ -1,51 +1,25 @@
module Kernel
- # :call-seq:
- # should(matcher)
- # should == expected
- # should === expected
- # should =~ expected
- #
- # receiver.should(matcher)
- # => Passes if matcher.matches?(receiver)
- #
- # receiver.should == expected #any value
- # => Passes if (receiver == expected)
- #
- # receiver.should === expected #any value
- # => Passes if (receiver === expected)
- #
- # receiver.should =~ regexp
- # => Passes if (receiver =~ regexp)
- #
- # See RSpec::Matchers for more information about matchers
- #
- # == Warning
- #
- # NOTE that this does NOT support receiver.should != expected.
- # Instead, use receiver.should_not == expected
+ # Passes if +matcher+ returns true. Available on every +Object+.
+ # @example
+ # actual.should eq(expected)
+ # actual.should be > 4
+ # @param [Matcher]
+ # matcher
+ # @param [String] message optional message to display when the expectation fails
+ # @return [PositiveExpectationHandler]
+ # @see RSpec::Matchers
def should(matcher=nil, message=nil, &block)
RSpec::Expectations::PositiveExpectationHandler.handle_matcher(self, matcher, message, &block)
end
-
- # :call-seq:
- # should_not(matcher)
- # should_not == expected
- # should_not === expected
- # should_not =~ expected
- #
- # receiver.should_not(matcher)
- # => Passes unless matcher.matches?(receiver)
- #
- # receiver.should_not == expected
- # => Passes unless (receiver == expected)
- #
- # receiver.should_not === expected
- # => Passes unless (receiver === expected)
- #
- # receiver.should_not =~ regexp
- # => Passes unless (receiver =~ regexp)
- #
- # See RSpec::Matchers for more information about matchers
+
+ # Passes if +matcher+ returns false. Available on every +Object+.
+ # @example
+ # actual.should_not eq(expected)
+ # @param [Matcher]
+ # matcher
+ # @param [String] message optional message to display when the expectation fails
+ # @return [NegativeExpectationHandler]
+ # @see RSpec::Matchers
def should_not(matcher=nil, message=nil, &block)
RSpec::Expectations::NegativeExpectationHandler.handle_matcher(self, matcher, message, &block)
end
View
148 lib/rspec/matchers.rb
@@ -1,16 +1,15 @@
module RSpec
# rspec-expecations provides a number of useful Matchers we use to compose
- # expectations. A Matcher is any object that responds to the following
- # methods:
+ # expectations. A Matcher is any object that responds to the following:
#
- # matches?(actual)
- # failure_message_for_should
+ # matches?(actual)
+ # failure_message_for_should
#
# These methods are also part of the matcher protocol, but are optional:
#
- # does_not_match?(actual)
- # failure_message_for_should_not
- # description #optional
+ # does_not_match?(actual)
+ # failure_message_for_should_not
+ # description #optional
#
# == Predicates
#
@@ -24,25 +23,25 @@ module RSpec
# All you need to do is write +should be_+ followed by the predicate without
# the question mark, and RSpec will figure it out from there. For example:
#
- # [].should be_empty => [].empty? #passes
- # [].should_not be_empty => [].empty? #fails
+ # [].should be_empty # => [].empty?() | passes
+ # [].should_not be_empty # => [].empty?() | fails
#
# In addtion to prefixing the predicate matchers with "be_", you can also use "be_a_"
# and "be_an_", making your specs read much more naturally:
#
- # "a string".should be_an_instance_of(String) =>"a string".instance_of?(String) #passes
+ # "a string".should be_an_instance_of(String) =>"a string".instance_of?(String) #passes
#
- # 3.should be_a_kind_of(Fixnum) => 3.kind_of?(Numeric) #passes
- # 3.should be_a_kind_of(Numeric) => 3.kind_of?(Numeric) #passes
- # 3.should be_an_instance_of(Fixnum) => 3.instance_of?(Fixnum) #passes
- # 3.should_not be_instance_of(Numeric) => 3.instance_of?(Numeric) #fails
+ # 3.should be_a_kind_of(Fixnum) # => 3.kind_of?(Numeric) | passes
+ # 3.should be_a_kind_of(Numeric) # => 3.kind_of?(Numeric) | passes
+ # 3.should be_an_instance_of(Fixnum) # => 3.instance_of?(Fixnum) | passes
+ # 3.should_not be_instance_of(Numeric) # => 3.instance_of?(Numeric) | fails
#
# RSpec will also create custom matchers for predicates like +has_key?+. To
# use this feature, just state that the object should have_key(:key) and RSpec will
# call has_key?(:key) on the target. For example:
#
- # {:a => "A"}.should have_key(:a) => {:a => "A"}.has_key?(:a) #passes
- # {:a => "A"}.should have_key(:b) => {:a => "A"}.has_key?(:b) #fails
+ # {:a => "A"}.should have_key(:a) # => {:a => "A"}.has_key?(:a) | passes
+ # {:a => "A"}.should have_key(:b) # => {:a => "A"}.has_key?(:b) | fails
#
# You can use this feature to invoke any predicate that begins with "has_", whether it is
# part of the Ruby libraries (like +Hash#has_key?+) or a method you wrote on your own class.
@@ -59,42 +58,45 @@ module RSpec
# zones on a virtual board. To specify that bob should be in zone 4, you
# could say:
#
- # bob.current_zone.should eql(Zone.new("4"))
+ # bob.current_zone.should eql(Zone.new("4"))
#
# But you might find it more expressive to say:
#
- # bob.should be_in_zone("4")
+ # bob.should be_in_zone("4")
#
# and/or
#
- # bob.should_not be_in_zone("3")
+ # bob.should_not be_in_zone("3")
#
# You can create such a matcher like so:
#
- # RSpec::Matchers.define :be_in_zone do |zone|
- # match do |player|
- # player.in_zone?(zone)
- # end
- # end
+ # RSpec::Matchers.define :be_in_zone do |zone|
+ # match do |player|
+ # player.in_zone?(zone)
+ # end
+ # end
#
# This will generate a <tt>be_in_zone</tt> method that returns a matcher
# with logical default messages for failures. You can override the failure
# messages and the generated description as follows:
#
- # RSpec::Matchers.define :be_in_zone do |zone|
- # match do |player|
- # player.in_zone?(zone)
- # end
- # failure_message_for_should do |player|
- # # generate and return the appropriate string.
- # end
- # failure_message_for_should_not do |player|
- # # generate and return the appropriate string.
- # end
- # description do
- # # generate and return the appropriate string.
- # end
- # end
+ # RSpec::Matchers.define :be_in_zone do |zone|
+ # match do |player|
+ # player.in_zone?(zone)
+ # end
+ #
+ # failure_message_for_should do |player|
+ # # generate and return the appropriate string.
+ # end
+ #
+ # failure_message_for_should_not do |player|
+ # # generate and return the appropriate string.
+ # end
+ #
+ # description do
+ # # generate and return the appropriate string.
+ # end
+ # end
#
# Each of the message-generation methods has access to the block arguments
# passed to the <tt>create</tt> method (in this case, <tt>zone</tt>). The
@@ -106,54 +108,56 @@ module RSpec
#
# You could also write a custom matcher from scratch, as follows:
#
- # class BeInZone
- # def initialize(expected)
- # @expected = expected
- # end
- # def matches?(target)
- # @target = target
- # @target.current_zone.eql?(Zone.new(@expected))
- # end
- # def failure_message_for_should
- # "expected #{@target.inspect} to be in Zone #{@expected}"
- # end
- # def failure_message_for_should_not
- # "expected #{@target.inspect} not to be in Zone #{@expected}"
- # end
- # end
+ # class BeInZone
+ # def initialize(expected)
+ # @expected = expected
+ # end
+ #
+ # def matches?(target)
+ # @target = target
+ # @target.current_zone.eql?(Zone.new(@expected))
+ # end
+ #
+ # def failure_message_for_should
+ # "expected #{@target.inspect} to be in Zone #{@expected}"
+ # end
+ #
+ # def failure_message_for_should_not
+ # "expected #{@target.inspect} not to be in Zone #{@expected}"
+ # end
+ # end
#
# ... and a method like this:
#
- # def be_in_zone(expected)
- # BeInZone.new(expected)
- # end
+ # def be_in_zone(expected)
+ # BeInZone.new(expected)
+ # end
#
# And then expose the method to your specs. This is normally done
# by including the method and the class in a module, which is then
# included in your spec:
#
- # module CustomGameMatchers
- # class BeInZone
- # ...
- # end
+ # module CustomGameMatchers
+ # class BeInZone
+ # # ...
+ # end
#
- # def be_in_zone(expected)
- # ...
- # end
- # end
+ # def be_in_zone(expected)
+ # # ...
+ # end
+ # end
#
- # describe "Player behaviour" do
- # include CustomGameMatchers
- # ...
- # end
+ # describe "Player behaviour" do
+ # include CustomGameMatchers
+ # # ...
+ # end
#
# or you can include in globally in a spec_helper.rb file <tt>require</tt>d
# from your spec file(s):
#
- # RSpec::Runner.configure do |config|
- # config.include(CustomGameMatchers)
- # end
- #
+ # RSpec::configure do |config|
+ # config.include(CustomGameMatchers)
+ # end
module Matchers
# Include Matchers for other test frameworks.
# Note that MiniTest _must_ come before TU because on ruby 1.9,
View
93 lib/rspec/matchers/be.rb
@@ -1,35 +1,36 @@
require 'rspec/matchers/dsl'
-RSpec::Matchers.define :be_true do
- match do |actual|
- actual
- end
-end
+module RSpec
+ module Matchers
-RSpec::Matchers.define :be_false do
- match do |actual|
- !actual
- end
-end
+ # @method be_true
+ RSpec::Matchers.define :be_true do
+ match do |actual|
+ actual
+ end
+ end
-RSpec::Matchers.define :be_nil do
- match do |actual|
- actual.nil?
- end
+ RSpec::Matchers.define :be_false do
+ match do |actual|
+ !actual
+ end
+ end
- failure_message_for_should do |actual|
- "expected: nil\n got: #{actual.inspect}"
- end
+ RSpec::Matchers.define :be_nil do
+ match do |actual|
+ actual.nil?
+ end
- failure_message_for_should_not do
- "expected: not nil\n got: nil"
- end
-end
+ failure_message_for_should do |actual|
+ "expected: nil\n got: #{actual.inspect}"
+ end
-module RSpec
- module Matchers
+ failure_message_for_should_not do
+ "expected: not nil\n got: nil"
+ end
+ end
- class Be #:nodoc:
+ class Be
include RSpec::Matchers::Pretty
def initialize(*args, &block)
@@ -177,36 +178,26 @@ def prefix_to_sentence
end
- # :call-seq:
- # should be_true
- # should be_false
- # should be_nil
- # should be_[arbitrary_predicate](*args)
- # should_not be_nil
- # should_not be_[arbitrary_predicate](*args)
- #
- # Given true, false, or nil, will pass if actual value is
- # true, false or nil (respectively). Given no args means
- # the caller should satisfy an if condition (to be or not to be).
- #
- # Predicates are any Ruby method that ends in a "?" and returns true or false.
- # Given be_ followed by arbitrary_predicate (without the "?"), RSpec will match
- # convert that into a query against the target object.
- #
- # The arbitrary_predicate feature will handle any predicate
- # prefixed with "be_an_" (e.g. be_an_instance_of), "be_a_" (e.g. be_a_kind_of)
- # or "be_" (e.g. be_empty), letting you choose the prefix that best suits the predicate.
+ # @example
+ # actual.should be_true
+ # actual.should be_false
+ # actual.should be_nil
+ # actual.should be_[arbitrary_predicate](*args)
+ # actual.should_not be_nil
+ # actual.should_not be_[arbitrary_predicate](*args)
#
- # == Examples
+ # Given true, false, or nil, will pass if actual value is true, false or
+ # nil (respectively). Given no args means the caller should satisfy an if
+ # condition (to be or not to be).
#
- # target.should be_true
- # target.should be_false
- # target.should be_nil
- # target.should_not be_nil
+ # Predicates are any Ruby method that ends in a "?" and returns true or
+ # false. Given be_ followed by arbitrary_predicate (without the "?"),
+ # RSpec will match convert that into a query against the target object.
#
- # collection.should be_empty #passes if target.empty?
- # target.should_not be_empty #passes unless target.empty?
- # target.should_not be_old_enough(16) #passes unless target.old_enough?(16)
+ # The arbitrary_predicate feature will handle any predicate prefixed with
+ # "be_an_" (e.g. be_an_instance_of), "be_a_" (e.g. be_a_kind_of) or "be_"
+ # (e.g. be_empty), letting you choose the prefix that best suits the
+ # predicate.
def be(*args)
args.empty? ?
Matchers::Be.new : equal(*args)

0 comments on commit ba6456d

Please sign in to comment.