[Solar-svn] Revision 2997

[pmjones at solarphp.com]

update comments


Modified: trunk/Solar/Sql/Model/Record.php
===================================================================
--- trunk/Solar/Sql/Model/Record.php	2008-03-13 01:04:38 UTC (rev 2996)
+++ trunk/Solar/Sql/Model/Record.php	2008-03-13 01:49:46 UTC (rev 2997)
@@ -474,7 +474,8 @@
     
     /**
      * 
-     * Saves this record to the database, inserting or updating as needed.
+     * Saves this record and all related records to the database, inserting or
+     * updating as needed.
      * 
      * Hook methods:
      * 
@@ -490,9 +491,13 @@
      * 5. `_postSave()` runs after all save operations, but before related
      *    records are saved.
      * 
+     * 6. `_preSaveRelated()` runs before saving related records.
      * 
-     * After _postSave(), we save each related Record and Collection object.
+     * 7. Each related record is saved, invoking the save() routine with all
+     *    its hooks on each related record.
      * 
+     * 8. `_postSaveRelated()` runs after all related records are saved.
+     * 
      * @param array $data An associative array of data to merge with existing
      * record data.
      * 
@@ -522,6 +527,16 @@
         }
     }
     
+    /**
+     * 
+     * Saves the current record, but only if the record is "dirty".
+     * 
+     * On saving, invokes the pre-save, pre- and post- insert/update,
+     * and post-save hooks.
+     * 
+     * @return void
+     * 
+     */
     protected function _save()
     {
         // only save if we're not clean
@@ -549,30 +564,6 @@
         }
     }
     
-    protected function _saveRelated()
-    {
-        $this->_preSaveRelated();
-        
-        // now save each related, but only if instantiated
-        foreach ($this->_model->related as $name => $info) {
-        
-            // use $this->_data[$name] **instead of** $this->$name,
-            // to avoid lazy-loading the related record (which in turn
-            // causes infinite recursion)
-            if (empty($this->_data[$name])) {
-                continue;
-            }
-        
-            if ($this->_data[$name] instanceof Solar_Sql_Model_Record ||
-                $this->_data[$name] instanceof Solar_Sql_Model_Collection) {
-                // is a record or collection, save them
-                $this->_data[$name]->save();
-            }
-        }
-        
-        $this->_postSaveRelated();
-    }
-    
     /**
      * 
      * User-defined pre-save logic.
@@ -595,14 +586,6 @@
     {
     }
     
-    protected function _preSaveRelated()
-    {
-    }
-    
-    protected function _postSaveRelated()
-    {
-    }
-    
     /**
      * 
      * Inserts the current record into the database, making calls to pre- and
@@ -696,6 +679,61 @@
     
     /**
      * 
+     * Saves each related record.
+     * 
+     * Invokes the pre- and post- saveRelated methods.
+     * 
+     * @return void
+     * 
+     */
+    protected function _saveRelated()
+    {
+        $this->_preSaveRelated();
+        
+        // now save each related, but only if instantiated
+        foreach ($this->_model->related as $name => $info) {
+        
+            // use $this->_data[$name] **instead of** $this->$name,
+            // to avoid lazy-loading the related record (which in turn
+            // causes infinite recursion)
+            if (empty($this->_data[$name])) {
+                continue;
+            }
+        
+            if ($this->_data[$name] instanceof Solar_Sql_Model_Record ||
+                $this->_data[$name] instanceof Solar_Sql_Model_Collection) {
+                // is a record or collection, save them
+                $this->_data[$name]->save();
+            }
+        }
+        
+        $this->_postSaveRelated();
+    }
+    
+    /**
+     * 
+     * User-defined logic to execute before saving related records.
+     * 
+     * @return void
+     * 
+     */
+    protected function _preSaveRelated()
+    {
+    }
+    
+    /**
+     * 
+     * User-defined logic to execute after saving related records.
+     * 
+     * @return void
+     * 
+     */
+    protected function _postSaveRelated()
+    {
+    }
+    
+    /**
+     * 
      * Deletes this record from the database.
      * 
      * @return void
@@ -985,6 +1023,16 @@
         return $this->_status;
     }
     
+    /**
+     * 
+     * Returns the exception (if any) generated by the most-recent call to the
+     * save() method.
+     * 
+     * @return Exception
+     * 
+     * @see save()
+     * 
+     */
     public function getSaveException()
     {
         return $this->_save_exception;