From e679a522d446cfaccde86657ceefcb369036c26d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jos=C3=A9=20Valim?= <jose.valim@gmail.com>
Date: Mon, 9 Feb 2009 23:44:56 +0100
Subject: [PATCH] Adding some comments in associations.

---
 .../associations/association_matcher.rb       | 44 +++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/lib/remarkable/active_record/macros/associations/association_matcher.rb b/lib/remarkable/active_record/macros/associations/association_matcher.rb
index 22e9220..86446bd 100644
--- a/lib/remarkable/active_record/macros/associations/association_matcher.rb
+++ b/lib/remarkable/active_record/macros/associations/association_matcher.rb
@@ -177,18 +177,62 @@ def macro_description
         end
       end
 
+
+      # Ensure that the belongs_to relationship exists.
+      #
+      # Examples:
+      #
+      #   should_belong_to :parent
+      #   it { should belong_to(:parent) }
+      #
       def belong_to(*associations)
         AssociationMatcher.new(:belongs_to, *associations)
       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 has_many :through
+      # * <tt>:dependent</tt> - tests that the association makes use of the dependent option.
+      #
+      # Examples:
+      #
+      #   should_have_many :friends
+      #   should_have_many :enemies, :through => :friends
+      #   should_have_many :enemies, :dependent => :destroy
+      #
+      #   it{ should have_many(:friends) }
+      #   it{ should have_many(:enemies, :through => :friends) }
+      #   it{ should have_many(:enemies, :dependent => :destroy) }
+      #
+      #
       def have_many(*associations)
         AssociationMatcher.new(:has_many, *associations)
       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.
+      #
+      # Examples:
+      #
+      #  should_have_one :god
+      #  it{ should have_one(:god) }
+      #
       def have_one(*associations)
         AssociationMatcher.new(:has_one, *associations)
       end
 
+      # Ensures that the has_and_belongs_to_many relationship exists, and that the join table is in place.
+      #
+      # Examples:
+      #
+      #  should_have_and_belong_to_many :posts, :cars
+      #  it{ should have_and_belong_to_many :posts, :cars }
+      #
       def have_and_belong_to_many(*associations)
         AssociationMatcher.new(:has_and_belongs_to_many, *associations)
       end