Added missing documentation for ActiveRecord matchers

lib/shoulda/active_record/matchers/association_matcher.rb

@@ -2,18 +2,52 @@ module Shoulda # :nodoc:
   module ActiveRecord # :nodoc:
     module Matchers
 
+      # Ensure that the belongs_to relationship exists.
+      #
+      #   it { should belong_to(:parent) }
+      #
       def belong_to(name)
         AssociationMatcher.new(:belongs_to, name)
       end
 
+      # Ensures that the has_many relationship exists.  Will also test that the
+      # associated table has the required columns.  Works with polymorphic
+      # associations.
+      #
+      # Options:
+      # * <tt>through</tt> - association name for <tt>has_many :through</tt>
+      # * <tt>dependent</tt> - tests that the association makes use of the
+      #   dependent option.
+      #
+      # Example:
+      #   it { should_have_many(:friends) }
+      #   it { should_have_many(:enemies).through(:friends) }
+      #   it { should_have_many(:enemies).dependent(:destroy) }
+      #
       def have_many(name)
         AssociationMatcher.new(:has_many, name)
       end
 
+      # Ensure that the has_one relationship exists.  Will also test that the
+      # associated table has the required columns.  Works with polymorphic
+      # associations.
+      #
+      # Options:
+      # * <tt>:dependent</tt> - tests that the association makes use of the
+      #   dependent option.
+      #
+      # Example:
+      #   it { should have_one(:god) } # unless hindu
+      #
       def have_one(name)
         AssociationMatcher.new(:has_one, name)
       end
 
+      # Ensures that the has_and_belongs_to_many relationship exists, and that
+      # the join table is in place.
+      #
+      #   it { should have_and_belong_to_many(:posts) }
+      #
       def have_and_belong_to_many(name)
         AssociationMatcher.new(:has_and_belongs_to_many, name)
       end

lib/shoulda/active_record/matchers/have_db_column_matcher.rb

@@ -6,10 +6,10 @@ module Matchers
       #
       # Options:
       # * <tt>of_type</tt> - db column type (:integer, :string, etc.)
-      #   <tt>with_options</tt> - same options available in migrations
-      #     (:default, :null, :limit, :precision, :scale)
+      # * <tt>with_options</tt> - same options available in migrations
+      #   (:default, :null, :limit, :precision, :scale)
       #
-      # Example:
+      # Examples:
       #   it { should_not have_db_column(:admin).of_type(:boolean) }
       #   it { should have_db_column(:salary).
       #                 of_type(:decimal).

lib/shoulda/active_record/matchers/have_index_matcher.rb

@@ -2,12 +2,20 @@ module Shoulda # :nodoc:
   module ActiveRecord # :nodoc:
     module Matchers
 
-      # Ensures the database column has specified index.
+      # Ensures that there are DB indices on the given columns or tuples of
+      # columns.
       #
       # Options:
-      # * <tt>unique</tt> - 
+      # * <tt>unique</tt> - whether or not the index has a unique
+      #   constraint. Use <tt>true</tt> to explicitly test for a unique
+      #   constraint.  Use <tt>false</tt> to explicitly test for a non-unique
+      #   constraint. Use <tt>nil</tt> if you don't care whether the index is
+      #   unique or not.  Default = <tt>nil</tt>
       #
-      # Example:
+      # Examples:
+      #
+      #   it { should have_index(:age) }
+      #   it { should have_index([:commentable_type, :commentable_id]) }
       #   it { should have_index(:ssn).unique(true) }
       #
       def have_index(columns)

lib/shoulda/active_record/matchers/have_named_scope_matcher.rb

@@ -2,6 +2,50 @@ module Shoulda # :nodoc:
   module ActiveRecord # :nodoc:
     module Matchers
 
+      # Ensures that the model has a method named scope_call that returns a
+      # NamedScope object with the proxy options set to the options you supply.
+      # scope_call can be either a symbol, or a Ruby expression in a String
+      # which will be evaled. The eval'd method call has access to all the same
+      # instance variables that an example would.
+      #
+      # Options:
+      #
+      #  * <tt>in_context</tt> - Any of the options that the named scope would
+      #    pass on to find.
+      #
+      # Example:
+      #
+      #   it { should have_named_scope(:visible).
+      #                 finding(:conditions => {:visible => true}) }
+      #
+      # Passes for
+      #
+      #   named_scope :visible, :conditions => {:visible => true}
+      #
+      # Or for
+      #
+      #   def self.visible
+      #     scoped(:conditions => {:visible => true})
+      #   end
+      #
+      # You can test lambdas or methods that return ActiveRecord#scoped calls:
+      #
+      #   it { should have_named_scope('recent(5)').finding(:limit => 5) }
+      #   it { should have_named_scope('recent(1)').finding(:limit => 1) }
+      #
+      # Passes for
+      #   named_scope :recent, lambda {|c| {:limit => c}}
+      #
+      # Or for
+      #
+      #   def self.recent(c)
+      #     scoped(:limit => c)
+      #   end
+      #
+      def have_named_scope(scope_call)
+        HaveNamedScopeMatcher.new(scope_call).in_context(self)
+      end
+
       class HaveNamedScopeMatcher # :nodoc:
 
         def initialize(scope_call)
@@ -76,10 +120,6 @@ def finds_correct_scope?
 
       end
 
-      def have_named_scope(scope_call)
-        HaveNamedScopeMatcher.new(scope_call).in_context(self)
-      end
-
     end
   end
 end

lib/shoulda/active_record/matchers/only_allow_numeric_values_matcher.rb

@@ -2,6 +2,20 @@ module Shoulda # :nodoc:
   module ActiveRecord # :nodoc:
     module Matchers
 
+      # Ensure that the attribute is numeric
+      #
+      # Options:
+      # * <tt>with_message</tt> - value the test expects to find in
+      #   <tt>errors.on(:attribute)</tt>. Regexp or string.  Defaults to the
+      #   translation for <tt>:not_a_number</tt>.
+      #
+      # Example:
+      #   it { should only_allow_numeric_values_for(:age) }
+      #
+      def only_allow_numeric_values_for(attr)
+        OnlyAllowNumericValuesMatcher.new(attr)
+      end
+
       class OnlyAllowNumericValuesMatcher < ValidationMatcher # :nodoc:
 
         def with_message(message)
@@ -20,9 +34,6 @@ def description
         end
       end
 
-      def only_allow_numeric_values_for(attr)
-        OnlyAllowNumericValuesMatcher.new(attr)
-      end
     end
   end
 end

lib/shoulda/active_record/matchers/require_acceptance_of_matcher.rb

@@ -2,6 +2,22 @@ module Shoulda # :nodoc:
   module ActiveRecord # :nodoc:
     module Matchers
 
+      # Ensures that the model cannot be saved the given attribute is not
+      # accepted.
+      #
+      # Options:
+      # * <tt>with_message</tt> - value the test expects to find in
+      #   <tt>errors.on(:attribute)</tt>. Regexp or string.  Defaults to the
+      #   translation for <tt>:accepted</tt>.
+      #
+      # Example:
+      #   it { should require_acceptance_of(:eula) }
+      #
+      def require_acceptance_of(attr)
+        RequireAcceptanceOfMatcher.
+          new(attr)
+      end
+
       class RequireAcceptanceOfMatcher < ValidationMatcher # :nodoc:
 
         def with_message(message)
@@ -21,10 +37,6 @@ def description
 
       end
 
-      def require_acceptance_of(attr)
-        RequireAcceptanceOfMatcher.
-          new(attr)
-      end
     end
   end
 end