snusnu-dm-accepts_nested_attributes 0.10.0 → 0.11.0

data/Manifest.txt

@@ -10,12 +10,11 @@ lib/dm-accepts_nested_attributes.rb
 lib/dm-accepts_nested_attributes/error_collecting.rb
 lib/dm-accepts_nested_attributes/model.rb
 lib/dm-accepts_nested_attributes/resource.rb
-lib/dm-accepts_nested_attributes/save.rb
 lib/dm-accepts_nested_attributes/transactional_save.rb
 lib/dm-accepts_nested_attributes/version.rb
 spec/spec.opts
 spec/spec_helper.rb
-spec/lib/rspec_tmbundle_support.rb
+spec/lib/constraint_support.rb
 spec/fixtures/person.rb
 spec/fixtures/profile.rb
 spec/fixtures/project.rb

data/README.textile

@@ -2,66 +2,7 @@ h2. dm-accepts_nested_attributes
 
 A DataMapper plugin that allows nested model attribute assignment like activerecord does.
 
-At the end of this file, you can see a list of all current integration specs.
-
-For more information on the progress, have a look at this README and also at
-"this article":http://sick.snusnu.info/2009/04/08/dm-accepts_nested_attributes/ on my blog, where I will try to comment on the
-development (problems).
-
-h2. Current limitations
-
-Interaction with @dm-validations@ is actually possible but not very well specced atm. I added @not null@
-constraints to all spec fixtures for now, but no other custom validations. All specs still pass. However,
-as long as I'm not decided on where to put the specs for interaction with @dm-validations@ (most probably
-inside @dm-validations@ would be the right place for these), I won't write many more specs for these scenarios,
-since it's very hard to decide where to stop, once I start writing some.
-
-Currently, the creation of the record together with all its join models, is not handled inside a transaction.
-This must definitely change! As soon as I find out why my initial experiments with transactions consistently
-yielded _no such table errors_ while migrating the specsuite (see "this pastie":http://pastie.org/446060), I
-will do my best to add this feature.
-
-h2. TODO
-
-* use transactions
-* update README to include more complete usecases
-* specs for custom validations (dm-validations in general)
-* specs for adding errors to the parent objects
-* reorganize specs and fix bugs
-* Adapt to datamapper/next
-
-h2. Implementation details
-
-This section mainly serves as a place for me to take notes during development.
-
-h3. Why isn't this implemented as options on association declarations?
-
-* I somehow like the declarative style of @accepts_nested_attributes_for@ better. it jumps out immediately.
-* The API for datamapper and activerecord is the same.
-* association definitions can already get quite long and "unreadable". chances are you overlook it!
-
-h3. Why doesn't accepts_nested_attributes_for take more than one association_name?
-
-While writing the unit specs for this method, I realised that there are way too many ways to call this
-method, which makes it "hard" to spec all possible calls. That's why I started to list Pros and Cons, and
-decided to support only one @association_name@ per call, at least for now.
-
-h4. Pros
-
-* less complex code
-* fewer ways to call the method (simpler to understand, easier to spec)
-* easier to read (nr of calls == nr of accessible associations, this could be seen as a con also)
-* easier (and more extensible) option handling
-** options don't implicitly apply to _all_ associations (could be seen as a con also?)
-** options can explicitly be applied to _only the desired_ associations
-** reject_if option maybe often makes more sense on exactly _one_ associaton (maybe not?)
-* no question what happens if the association_name is invalid (the whole call is invalid)
-** with at least one _invalid_ association_name, what happens for the other _valid_ ones?  
-
-h4. Cons
-
-* needs more method calls (overhead should be minimal)
-* options that apply to more than one attribute need to be duplicated (maybe a Pro because of readability)
+Current documentation can always be found at "rdoc.info":http://rdoc.info/projects/snusnu/dm-accepts_nested_attributes
 
 h3. Examples
 
@@ -71,10 +12,6 @@ The following example illustrates the use of this plugin.
 <code>
 require "rubygems"
 
-gem 'dm-core',                      '0.9.11'
-gem 'dm-validations',               '0.9.11'
-gem 'dm-accepts_nested_attributes', '0.0.1'
-
 require "dm-core"
 require "dm-validations"
 require "dm-accepts_nested_attributes"
@@ -89,9 +26,10 @@ class Person
   has 1, :profile
   has n, :project_memberships
   has n, :projects, :through => :project_memberships
+
   accepts_nested_attributes_for :profile
   accepts_nested_attributes_for :projects
-  
+
   # adds the following instance methods
   # #profile_attributes
   # #projects_attributes
@@ -102,8 +40,9 @@ class Profile
   property :id,      Serial
   property :person_id, Integer
   belongs_to :person
+
   accepts_nested_attributes_for :person
-  
+
   # adds the following instance methods
   # #person_attributes
 end
@@ -114,6 +53,7 @@ class Project
   has n, :tasks
   has n, :project_memberships
   has n, :people, :through => :project_memberships
+
   accepts_nested_attributes_for :tasks
   accepts_nested_attributes_for :people
   
@@ -129,9 +69,6 @@ class ProjectMembership
   property :project_id, Integer
   belongs_to :person
   belongs_to :project
-  
-  # nothing added here
-  # code only listed to provide complete example env
 end
 
 class Task
@@ -139,133 +76,30 @@ class Task
   property :id,         Serial
   property :project_id, Integer
   belongs_to :project
-  
-  # nothing added here
-  # code only listed to provide complete example env
 end
 
 DataMapper.auto_migrate!
 </code>
 </pre>
 
-h2. Current Integration Specs
-
-<pre>
-<code>
-DataMapper::NestedAttributes Profile.belongs_to(:person) accepts_nested_attributes_for(:person)
-- should allow to create a new person via Profile#person_attributes
-- should allow to update an existing person via Profile#person_attributes
-- should not allow to delete an existing person via Profile#person_attributes
-
-DataMapper::NestedAttributes Profile.belongs_to(:person) accepts_nested_attributes_for(:person, :allow_destroy => false)
-- should allow to create a new person via Profile#person_attributes
-- should allow to update an existing person via Profile#person_attributes
-- should not allow to delete an existing person via Profile#person_attributes
-
-DataMapper::NestedAttributes Profile.belongs_to(:person) accepts_nested_attributes_for(:person, :allow_destroy = true)
-- should allow to create a new person via Profile#person_attributes
-- should allow to update an existing person via Profile#person_attributes
-- should allow to delete an existing person via Profile#person_attributes
-
-DataMapper::NestedAttributes Profile.belongs_to(:person) accepts_nested_attributes_for :person,  :reject_if => :foo
-- should allow to create a new person via Profile#person_attributes
-- should allow to update an existing person via Profile#person_attributes
-- should not allow to delete an existing person via Profile#person_attributes
-
-DataMapper::NestedAttributes Profile.belongs_to(:person) accepts_nested_attributes_for :person,  :reject_if => lambda { |attrs| true }
-- should not allow to create a new person via Profile#person_attributes
-- should not allow to delete an existing person via Profile#person_attributes
-
-DataMapper::NestedAttributes Profile.belongs_to(:person) accepts_nested_attributes_for :person,  :reject_if => lambda { |attrs| false }
-- should allow to create a new person via Profile#person_attributes
-- should allow to update an existing person via Profile#person_attributes
-- should not allow to delete an existing person via Profile#person_attributes
-
-DataMapper::NestedAttributes Person.has(1, :profile) accepts_nested_attributes_for(:profile)
-- should allow to create a new profile via Person#profile_attributes
-- should allow to update an existing profile via Person#profile_attributes
-- should not allow to delete an existing profile via Person#profile_attributes
-
-DataMapper::NestedAttributes Person.has(1, :profile) accepts_nested_attributes_for(:profile, :allow_destroy => false)
-- should allow to create a new profile via Person#profile_attributes
-- should allow to update an existing profile via Person#profile_attributes
-- should not allow to delete an existing profile via Person#profile_attributes
-
-DataMapper::NestedAttributes Person.has(1, :profile) accepts_nested_attributes_for(:profile, :allow_destroy => true)
-- should allow to create a new profile via Person#profile_attributes
-- should allow to update an existing profile via Person#profile_attributes
-- should allow to delete an existing profile via Person#profile_attributes
-
-DataMapper::NestedAttributes Person.has(1, :profile) accepts_nested_attributes_for :profile,  :reject_if => :foo
-- should allow to create a new profile via Person#profile_attributes
-- should allow to update an existing profile via Person#profile_attributes
-- should not allow to delete an existing profile via Person#profile_attributes
-
-DataMapper::NestedAttributes Person.has(1, :profile) accepts_nested_attributes_for :profile,  :reject_if => lambda { |attrs| true }
-- should not allow to create a new profile via Person#profile_attributes
-- should not allow to delete an existing profile via Person#profile_attributes
-
-DataMapper::NestedAttributes Person.has(1, :profile) accepts_nested_attributes_for :profile,  :reject_if => lambda { |attrs| false }
-- should allow to create a new profile via Person#profile_attributes
-- should allow to update an existing profile via Person#profile_attributes
-- should not allow to delete an existing profile via Person#profile_attributes
-
-DataMapper::NestedAttributes Project.has(n, :tasks) accepts_nested_attributes_for(:tasks)
-- should allow to create a new task via Project#tasks_attributes
-- should allow to update an existing task via Project#tasks_attributes
-- should not allow to delete an existing task via Profile#tasks_attributes
-
-DataMapper::NestedAttributes Project.has(n, :tasks) accepts_nested_attributes_for(:tasks, :allow_destroy => false)
-- should allow to create a new task via Project#tasks_attributes
-- should allow to update an existing task via Project#tasks_attributes
-- should not allow to delete an existing task via Profile#tasks_attributes
-
-DataMapper::NestedAttributes Project.has(n, :tasks) accepts_nested_attributes_for(:tasks, :allow_destroy => true)
-- should allow to create a new task via Project#tasks_attributes
-- should allow to update an existing task via Project#tasks_attributes
-- should allow to delete an existing task via Profile#tasks_attributes
-
-DataMapper::NestedAttributes Project.has(n, :tasks) accepts_nested_attributes_for :tasks,  :reject_if => :foo
-- should allow to create a new task via Project#tasks_attributes
-- should allow to update an existing task via Project#tasks_attributes
-- should not allow to delete an existing task via Profile#tasks_attributes
-
-DataMapper::NestedAttributes Project.has(n, :tasks) accepts_nested_attributes_for :tasks,  :reject_if => lambda { |attrs| true }
-- should not allow to create a new task via Project#tasks_attributes
-- should not allow to delete an existing task via Profile#tasks_attributes
-
-DataMapper::NestedAttributes Project.has(n, :tasks) accepts_nested_attributes_for :tasks,  :reject_if => lambda { |attrs| false }
-- should allow to create a new task via Project#tasks_attributes
-- should allow to update an existing task via Project#tasks_attributes
-- should not allow to delete an existing task via Profile#tasks_attributes
-
-DataMapper::NestedAttributes Person.has(n, :projects, :through => :project_memberships) accepts_nested_attributes_for(:projects)
-- should allow to create a new project via Person#projects_attributes
-- should allow to update an existing project via Person#projects_attributes
-- should not allow to delete an existing project via Person#projects_attributes
+h2. Current limitations
 
-DataMapper::NestedAttributes Person.has(n, :projects, :through => :project_memberships) accepts_nested_attributes_for(:projects, :allow_destroy => false)
-- should allow to create a new project via Person#projects_attributes
-- should allow to update an existing project via Person#projects_attributes
-- should not allow to delete an existing project via Person#projects_attributes
+There are some minor limitations at the moment but I hope that these will be resolved some time soon.
 
-DataMapper::NestedAttributes Person.has(n, :projects, :through => :project_memberships) accepts_nested_attributes_for(:projects, :allow_destroy = true)
-- should allow to create a new project via Person#projects_attributes
-- should allow to update an existing project via Person#projects_attributes
-- should allow to delete an existing project via Person#projects_attributes
+h3. marking for destruction
 
-DataMapper::NestedAttributes Person.has(n, :projects, :through => :project_memberships) accepts_nested_attributes_for :projects,  :reject_if => :foo
-- should allow to create a new project via Person#projects_attributes
-- should allow to update an existing project via Person#projects_attributes
-- should not allow to delete an existing project via Person#projects_attributes
+@many_to_one, one_to_one and one_to_many@ relationships all perform the deleting of nested models by _marking them for destruction_. This means, that as long as you don't call #save on your resource, the nested models won't get destroyed. However, this is currently _not_ the case for @many_to_many@ relationships. The @join and target resources@ both get destroyed immediately when calling the nested attributes writer.
 
-DataMapper::NestedAttributes Person.has(n, :projects, :through => :project_memberships) accepts_nested_attributes_for :projects,  :reject_if => lambda { |attrs| true }
-- should not allow to create a new project via Person#projects_attributes
-- should not allow to delete an existing project via Person#projects_attributes
+For the above example this would mean that when you issue the code below, it would result in immediate deletion of the intermediate @ProjectMembership@ and the @Project@ resource.
 
-DataMapper::NestedAttributes Person.has(n, :projects, :through => :project_memberships) accepts_nested_attributes_for :projects,  :reject_if => lambda { |attrs| false }
-- should allow to create a new project via Person#projects_attributes
-- should allow to update an existing project via Person#projects_attributes
-- should not allow to delete an existing project via Person#projects_attributes
+<pre>
+<code>
+person.projects_attributes = { :id => valid_project_id, :_delete => true }
 </code>
 </pre>
+
+h2. TODO
+
+* collect validation errors from related resources
+* update README to include more complete usecases
+* think about replacing :reject_if with :if and :unless

data/TODO

@@ -1,8 +1,6 @@
 TODO
 ====
 
-* add specs for :reject_if => :foo option, but think about _where_ first!
-* think about supporting :reject_unless in addition to :reject_if
-* think about generalizing :reject_if to not only work for new? resources
-* think about :allow_destroy accepting the same parameters like :reject_if
-  (Symbol, String, #call)
+* collect validation errors from related resources
+* update README to include more complete usecases
+* think about replacing :reject_if with :if and :unless

data/lib/dm-accepts_nested_attributes.rb

@@ -4,10 +4,8 @@ require 'dm-core'
 dir = Pathname(__FILE__).dirname.expand_path / 'dm-accepts_nested_attributes'
 
 require dir / 'model'
-#require dir / 'save'
 require dir / 'resource'
 
 # Activate the plugin
 DataMapper::Model.append_extensions(DataMapper::NestedAttributes::Model)
-#DataMapper::Model.append_inclusions(DataMapper::NestedAttributes::Save)
 DataMapper::Model.append_inclusions(DataMapper::NestedAttributes::CommonResourceSupport)

data/lib/dm-accepts_nested_attributes/model.rb

@@ -2,7 +2,8 @@ module DataMapper
   module NestedAttributes
     
     ##
-    # raised by accepts_nested_attributes_for
+    # Named plugin exception that gets raised by
+    # @see accepts_nested_attributes_for
     # if the passed options don't make sense
     class InvalidOptions < ArgumentError; end
     
@@ -11,22 +12,26 @@ module DataMapper
       ##
       # Allows any association to accept nested attributes.
       #
-      # @param association_name [Symbol, String]
+      # @param [Symbol, String] association_name
       #   The name of the association that should accept nested attributes
       #
-      # @param options [Hash, nil]
+      # @param [Hash, nil] options
       #   List of resources to initialize the Collection with
       #
-      # @option :reject_if [Symbol, String, #call]
+      # @option [Symbol, String, #call] :reject_if
       #   An instance method name or an object that respond_to?(:call), which
       #   stops a new record from being created, if it evaluates to true.
       #
-      # @option :allow_destroy [true, false]
+      # @option [true, false] :allow_destroy
       #   If true, allow destroying the association via the generated writer
       #   If false, prevent destroying the association via the generated writer
       #   defaults to false
       #
+      # @raise [DataMapper::NestedAttributes::InvalidOptions]
+      #   A named exception class indicating invalid options
+      #
       # @return nil
+      #
       def accepts_nested_attributes_for(association_name, options = {})
         
         # ----------------------------------------------------------------------------------
@@ -51,8 +56,6 @@ module DataMapper
         
         include ::DataMapper::NestedAttributes::Resource
         
-        add_save_behavior
-
         # TODO i wonder if this is the best place here?
         # the transactional save behavior is definitely not needed for all resources,
         # but it's necessary for resources that accept nested attributes
@@ -78,33 +81,58 @@ module DataMapper
       end
       
       ##
-      # The options given to the accepts_nested_attributes method
-      # They are guaranteed to be valid if they made it this far.
+      # The options given to the accepts_nested_attributes method.
+      #
+      # @return [Hash]
+      #   The options given to the accepts_nested_attributes method
       #
-      # @return [Hash] The options given to the accepts_nested_attributes method
-      # @see accepts_nested_attributes
       def options_for_nested_attributes
         @options_for_nested_attributes ||= {}
       end
 
       private
 
-      def add_save_behavior
-        require Pathname(__FILE__).dirname.expand_path + 'save'
-        include ::DataMapper::NestedAttributes::Save
-      end
-
+      ##
+      # Provides a hook to include or disable customized transactional save behavior.
+      # Override this method to customize the implementation or disable it altogether.
+      # The current implementation in @see DataMapper::NestedAttributes::TransactionalSave
+      # simply wraps the saving of the complete object tree inside a transaction
+      # and rolls back in case any exceptions are raised, or any of the calls to
+      # @see DataMapper::Resource#save returned false
+      #
+      # @return Not specified
+      #
       def add_transactional_save_behavior
         require Pathname(__FILE__).dirname.expand_path + 'transactional_save'
         include ::DataMapper::NestedAttributes::TransactionalSave
       end
 
+      ##
+      # Provides a hook to include or disable customized error collecting behavior.
+      # Overwrite this method to customize the implementation or disable it altogether.
+      # The current implementation in @see DataMapper::NestedAttributes::ValidationErrorCollecting
+      # simply attaches all errors of related resources to the object that was initially saved.
+      #
+      # @return Not specified
+      #
       def add_error_collection_behavior
         require Pathname(__FILE__).dirname.expand_path + 'error_collecting'
         include ::DataMapper::NestedAttributes::ValidationErrorCollecting
       end
-      
-      
+
+      ##
+      # Checks options passed to @see accepts_nested_attributes_for
+      # If any of the given options is invalid, this method will raise
+      # @see DataMapper::NestedAttributes::InvalidOptions
+      #
+      # @param [Hash, nil] options
+      #   The options passed to @see accepts_nested_attributes_for
+      #
+      # @raise [DataMapper::NestedAttributes::InvalidOptions]
+      #   A named exception class indicating invalid options
+      #
+      # @return [nil]
+      #
       def assert_valid_options_for_nested_attributes(options)
         
         assert_kind_of 'options', options, Hash

data/lib/dm-accepts_nested_attributes/resource.rb

@@ -1,6 +1,14 @@
 module DataMapper
   module NestedAttributes
     
+    ##
+    # Extensions and customizations for @see DataMapper::Resource
+    # that are needed if the @see DataMapper::Resource wants to
+    # accept nested attributes for any given relationship.
+    # Basically, this module provides functionality that allows
+    # either assignment or marking for destruction of related parent
+    # and child associations, based on the given attributes and what
+    # kind of relationship should be altered.
     module Resource
       
       ##
@@ -15,16 +23,27 @@ module DataMapper
       # For now, this method basically is a no-op, but at least it provides a hook where
       # everyone can perform it's own sanitization by overwriting this method.
       #
-      # @return [Hash] The sanitized attributes
+      # @param attributes [Hash]
+      #   The attributes to sanitize
+      #
+      # @return [Hash]
+      #   The sanitized attributes
+      #
       def sanitize_nested_attributes(attributes)
         attributes # noop
       end
       
       private
 
+      ##
       # Attribute hash keys that should not be assigned as normal attributes.
-      # These hash keys are nested attributes implementation details.
-      UNASSIGNABLE_KEYS = [ :id, :_delete ]
+      #
+      # @return [#each]
+      #   The model key and :_delete, the latter being a special value
+      #   used to mark a resource for destruction
+      def unassignable_keys
+        model.key.to_a << :_delete
+      end
     
     
       ##
@@ -50,12 +69,12 @@ module DataMapper
       def assign_nested_attributes_for_related_resource(relationship, attributes)
         if attributes[:id].blank?
           return if reject_new_record?(relationship, attributes)
-          new_record = relationship.target_model.new(attributes.except(*UNASSIGNABLE_KEYS))
+          new_record = relationship.target_model.new(attributes.except(*unassignable_keys))
           relationship.set(self, new_record)
         else
           existing_record = relationship.get(self)
           if existing_record && existing_record.id.to_s == attributes[:id].to_s
-            assign_to_or_mark_for_destruction(relationship, existing_record, attributes)
+            assign_or_mark_for_destruction(relationship, existing_record, attributes)
           end
         end
       end
@@ -104,11 +123,11 @@ module DataMapper
           
           if attributes[:id].blank?
             next if reject_new_record?(relationship, attributes)
-            relationship.get(self).new(attributes.except(*UNASSIGNABLE_KEYS))
+            relationship.get(self).new(attributes.except(*unassignable_keys))
           else
             collection = relationship.get(self)
-            if existing_record = collection.detect { |record| record.id.to_s == attributes[:id].to_s }
-              assign_to_or_mark_for_destruction(relationship, existing_record, attributes)
+            if existing_record = collection.get(attributes[:id])
+              assign_or_mark_for_destruction(relationship, existing_record, attributes)
             end
           end
           
@@ -129,54 +148,82 @@ module DataMapper
       #   All attributes except @see UNASSIGNABLE_KEYS will be assigned
       #
       # @return nil
-      def assign_to_or_mark_for_destruction(relationship, resource, attributes)
+      def assign_or_mark_for_destruction(relationship, resource, attributes)
         allow_destroy = self.class.options_for_nested_attributes[relationship][:allow_destroy]
         if has_delete_flag?(attributes) && allow_destroy
-          resource.mark_for_destruction
+          if relationship.is_a?(DataMapper::Associations::ManyToMany::Relationship)
+
+            target_query      = relationship.target_key.zip(resource.key).to_hash
+            target_collection = relationship.get(self, target_query)
+
+            unless target_collection.empty?
+
+              target_collection.send(:intermediaries, target_collection).each do |intermediary|
+                intermediary.mark_for_destruction
+              end
+
+              target_collection.each { |r| r.mark_for_destruction }
+
+            end
+
+          else
+            resource.mark_for_destruction
+          end
         else
-          resource.update(attributes.except(*UNASSIGNABLE_KEYS))
+          resource.attributes = attributes.except(*unassignable_keys)
+          resource.save
         end
       end
 
       ##
-      # Determines if a hash contains a truthy _delete key.
+      # Determines if the given attributes hash contains a truthy :_delete key.
       #
-      # @param hash [Hash] The hash to test
+      # @param attributes [Hash] The attributes to test
       #
-      # @return [Boolean]
-      #   true, if hash containts a truthy _delete key
-      #   false, otherwise
-      def has_delete_flag?(hash)
-        # TODO find out if this activerecord code needs to be ported
-        # ConnectionAdapters::Column.value_to_boolean hash['_delete']
-        hash[:_delete]
+      # @return [TrueClass, FalseClass]
+      #   true, if attributes contains a truthy :_delete key
+      def has_delete_flag?(attributes)
+        !!attributes[:_delete]
       end
     
       ##
-      # Determines if a new record should be build by checking for
-      # has_delete_flag? or if a <tt>:reject_if</tt> proc exists for this
-      # association and evaluates to +true+.
+      # Determines if a new record should be built with the given attributes.
+      # Rejects a new record if @see has_delete_flag? returns true for the given attributes,
+      # or if a :reject_if guard exists for the passed relationship that evaluates to +true+.
       #
       # @param relationship [DataMapper::Associations::Relationship]
-      #   The relationship backing the association. 
-      #   Assignment will happen on the target end of the relationship
+      #   The relationship backing the association.
       #
       # @param attributes [Hash]
-      #   The attributes to assign to the relationship's target end
-      #   All attributes except @see UNASSIGNABLE_KEYS will be assigned
+      #   The attributes to test with @see has_delete_flag?
       #
-      # @return [Boolean]
-      #   true, if the given attributes won't be rejected
-      #   false, otherwise
+      # @return [TrueClass, FalseClass]
+      #   true, if the given attributes will be rejected
       def reject_new_record?(relationship, attributes)
         guard = self.class.options_for_nested_attributes[relationship][:reject_if]
         return false if guard.nil? # if relationship guard is nil, nothing will be rejected
         has_delete_flag?(attributes) || evaluate_reject_new_record_guard(guard, attributes)
       end
       
+      ##
+      # Evaluates the given guard by calling it with the given attributes
+      #
+      # @param [Symbol, String, #call] guard
+      #   An instance method name or an object that respond_to?(:call), which
+      #   would stop a new record from being created, if it evaluates to true.
+      #
+      # @param [Hash] attributes
+      #   The attributes to pass to the guard for evaluating if it should reject
+      #   the creation of a new resource
+      #
+      # @raise ArgumentError
+      #   If the given guard doesn't match [Symbol, String, #call]
+      #
+      # @return [true, false]
+      #   The value returned by evaluating the guard
       def evaluate_reject_new_record_guard(guard, attributes)
         if guard.is_a?(Symbol) || guard.is_a?(String)
-          send(guard)
+          send(guard, attributes)
         elsif guard.respond_to?(:call)
           guard.call(attributes)
         else
@@ -185,18 +232,48 @@ module DataMapper
         end
       end
       
-      def normalize_attributes_collection(attributes_collection)
-        if attributes_collection.is_a?(Hash)
-          attributes_collection.sort_by { |index, _| index.to_i }.map { |_, attributes| attributes }
+      ##
+      # Make sure to return a collection of attribute hashes.
+      # If passed an attributes hash, map it to its attributes
+      #
+      # @param attributes [Hash, #each]
+      #   An attributes hash or a collection of attribute hashes
+      #
+      # @return [#each]
+      #   A collection of attribute hashes
+      def normalize_attributes_collection(attributes)
+        if attributes.is_a?(Hash)
+          attributes.map { |_, attributes| attributes }
         else
-          attributes_collection
+          attributes
         end
       end
       
     end
     
+    ##
+    # This module provides basic support for accepting nested attributes,
+    # that every @see DataMapper::Resource must include. It includes methods
+    # that allow a resource to be marked for destruction and it provides an
+    # overwritten version of @see DataMapper::Resource#save_self that either
+    # destroys a resource if it's @see marked_for_destruction? or performs
+    # an ordinary save by delegating to super
+    #
     module CommonResourceSupport
 
+      ##
+      # If self is marked for destruction, destroy self
+      # else, save self by delegating to super method.
+      #
+      # @return The same value that super returns
+      def save_self
+        if marked_for_destruction?
+          saved? ? destroy : true
+        else
+          super
+        end
+      end
+
       ##
       # remove mark for destruction if present
       # before delegating reload behavior to super
@@ -210,11 +287,10 @@ module DataMapper
       ##
       # Test if this resource is marked for destruction
       #
-      # @return [Boolean]
-      #   true, if this resource is marked for destruction
-      #   false, otherwise
+      # @return [true, false]
+      #   true if this resource is marked for destruction
       def marked_for_destruction?
-        @marked_for_destruction
+        !!@marked_for_destruction
       end
 
       ##