A little formatting and documentation.

lib/Doctrine.php

@@ -115,6 +115,7 @@ final class Doctrine
     const PARAM_NULL = 0;
     const PARAM_STMT = 4;
     const PARAM_STR = 2;
+
     /**
      * ATTRIBUTE CONSTANTS
      */
@@ -180,7 +181,6 @@ final class Doctrine
     const ATTR_RECORD_LISTENER      = 154;
     const ATTR_THROW_EXCEPTIONS     = 155;
 
-
     /**
      * LIMIT CONSTANTS
      */
@@ -321,27 +321,27 @@ final class Doctrine
      */
 
     /**
-     * turns of exporting
+     * EXPORT_NONE
      */
     const EXPORT_NONE               = 0;
 
     /**
-     * export tables
+     * EXPORT_TABLES
      */
     const EXPORT_TABLES             = 1;
 
     /**
-     * export constraints
+     * EXPORT_CONSTRAINTS
      */
     const EXPORT_CONSTRAINTS        = 2;
 
     /**
-     * export plugins
+     * EXPORT_PLUGINS
      */
     const EXPORT_PLUGINS            = 4;
 
     /**
-     * export all
+     * EXPORT_ALL
      */
     const EXPORT_ALL                = 7;
 
@@ -350,6 +350,9 @@ final class Doctrine
      */
     const HYDRATE_RECORD            = 2;
     
+    /**
+     * HYDRATE_ARRAY
+     */
     const HYDRATE_ARRAY             = 3;
 
     /**
@@ -357,40 +360,66 @@ final class Doctrine
      */
     const VALIDATE_NONE             = 0;
 
+    /**
+     * VALIDATE_LENGTHS
+     */
     const VALIDATE_LENGTHS          = 1;
 
+    /**
+     * VALIDATE_TYPES
+     */
     const VALIDATE_TYPES            = 2;
 
+    /**
+     * VALIDATE_CONSTRAINTS
+     */
     const VALIDATE_CONSTRAINTS      = 4;
 
+    /**
+     * VALIDATE_ALL
+     */
     const VALIDATE_ALL              = 7;
 
     /**
+     * IDENTIFIER_AUTOINC
+     *
      * constant for auto_increment identifier
      */
     const IDENTIFIER_AUTOINC        = 1;
 
     /**
+     * IDENTIFIER_SEQUENCE
+     *
      * constant for sequence identifier
      */
     const IDENTIFIER_SEQUENCE       = 2;
 
     /**
+     * IDENTIFIER_NATURAL
+     *
      * constant for normal identifier
      */
     const IDENTIFIER_NATURAL        = 3;
 
     /**
+     * IDENTIFIER_COMPOSITE
+     *
      * constant for composite identifier
      */
     const IDENTIFIER_COMPOSITE      = 4;
 
     /**
+     * Path
+     *
      * @var string $path            doctrine root directory
      */
     private static $_path;
 
     /**
+     * Debug
+     *
+     * Bool true/false
+     *
      * @var boolean $_debug
      */
     private static $_debug = false;
@@ -505,7 +534,7 @@ final class Doctrine
      * Recursively load all models from a directory or array of directories
      * 
      * @param string $directory Path to directory of models or array of directory paths
-     * @return void
+     * @return array $loadedModels
      */
     public static function loadModels($directory)
     {
@@ -535,8 +564,11 @@ final class Doctrine
      *
      * Get all the loaded models, you can provide an array of classes or it will use get_declared_classes()
      * 
+     * Will filter through an array of classes and return the Doctrine_Records out of them.
+     * If you do not specify $classes it will return all of the currently loaded Doctrine_Records
+     *
      * @param $classes Array of classes to filter through, otherwise uses get_declared_classes()
-     * @return void
+     * @return array $loadedModels
      */
     public static function getLoadedModels($classes = null)
     {
@@ -548,9 +580,7 @@ final class Doctrine
         
         $loadedModels = array();
         
-        // we iterate trhough the diff of previously declared classes
+        foreach ((array) $classes as $name) {
-        // and currently declared classes
-        foreach ($classes as $name) {
             $class = new ReflectionClass($name);
             
             // Skip the following classes
@@ -575,7 +605,7 @@ final class Doctrine
      * Get the connection object for a table by the actual table name
      * 
      * @param string $tableName 
-     * @return void
+     * @return object Doctrine_Connection
      */
     public static function getConnectionByTableName($tableName)
     {
@@ -601,6 +631,7 @@ final class Doctrine
      * @param string $directory Directory to write your models to
      * @param array $databases Array of databases to generate models for
      * @return boolean
+     * @throws Exception
      */
     public static function generateModelsFromDb($directory, array $databases = array())
     {
@@ -630,6 +661,7 @@ final class Doctrine
         
         return $result;
     }
+
     /**
      * generateModelsFromYaml
      *
@@ -664,7 +696,7 @@ final class Doctrine
      * generateSqlFromModels
      *
      * @param string $directory 
-     * @return void
+     * @return string $build  String of sql queries. One query per line
      */
     public static function generateSqlFromModels($directory = null)
     {
@@ -772,22 +804,12 @@ final class Doctrine
      */
     public static function loadData($yamlPath, $append = false)
     {
-        $delete = isset($append) ? ($append ? false : true) : true;
-
-        if ($delete)
-        {
-            $models = Doctrine::getLoadedModels();
-
-            foreach ($models as $model)
-            {
-                $model = new $model();
-
-                $model->getTable()->createQuery()->delete($model)->execute();
-            }
-        }
-
         $data = new Doctrine_Data();
         
+        if (!$append) {
+            $data->purge();
+        }
+        
         return $data->importData($yamlPath, 'yml');
     }
 
@@ -802,22 +824,12 @@ final class Doctrine
      */
     public static function loadDummyData($append, $num = 5)
     {
-        $delete = isset($append) ? ($append ? false : true) : true;
-
-        if ($delete)
-        {
-          $models = Doctrine::getLoadedModels();
-
-          foreach ($models as $model)
-          {
-            $model = new $model();
-
-            $model->getTable()->createQuery()->delete($model)->execute();
-          }
-        }
-        
         $data = new Doctrine_Data();
 
+        if (!$append) {
+          $data->purge();
+        }
+        
         return $data->importDummyData($num);
     }
     
@@ -828,7 +840,8 @@ final class Doctrine
      *
      * @param string $migrationsPath Path to migrations directory which contains your migration classes
      * @param string $to Version you wish to migrate to.
-     * @return void
+     * @return bool true
+     * @throws new Doctrine_Migration_Exception
      */
     public static function migrate($migrationsPath, $to = null)
     {
@@ -844,7 +857,6 @@ final class Doctrine
      *
      * @param string $className Name of the Migration class to generate
      * @param string $migrationsPath Path to directory which contains your migration classes
-     * @package default
      */
     public static function generateMigrationClass($className, $migrationsPath)
     {
@@ -858,6 +870,7 @@ final class Doctrine
      *
      * @param string $migrationsPath 
      * @return void
+     * @throws new Doctrine_Migration_Exception
      */
     public static function generateMigrationsFromDb($migrationsPath)
     {
@@ -903,6 +916,17 @@ final class Doctrine
         return Doctrine_Manager::connection($adapter, $name);
     }
     
+    /**
+     * fileFinder
+     *
+     * @param string $type 
+     * @return void
+     */
+    public static function fileFinder($type)
+    {
+        return Doctrine_FileFinder::type($type);
+    }
+    
     /**
      * compile
      * method for making a single file of most used doctrine runtime components

lib/Doctrine/Cli.php

@@ -1,6 +1,6 @@
 <?php
 /*
- *  $Id: Task.php 2761 2007-10-07 23:42:29Z zYne $
+ *  $Id: Cli.php 2761 2007-10-07 23:42:29Z zYne $
  *
  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
@@ -52,6 +52,7 @@ class Doctrine_Cli
      *
      * @param string $args 
      * @return void
+     * @throws new Doctrine_Cli_Exception
      */
     public function run($args)
     {
@@ -88,7 +89,7 @@ class Doctrine_Cli
      *
      * @param string $taskInstance 
      * @param string $args 
-     * @return void
+     * @return array $prepared
      */
     protected function prepareArgs($taskInstance, $args)
     {
@@ -132,6 +133,8 @@ class Doctrine_Cli
     /**
      * printTasks
      *
+     * Prints an index of all the available tasks in the CLI instance
+     * 
      * @return void
      */
     public function printTasks()
@@ -189,7 +192,7 @@ class Doctrine_Cli
      * loadTasks
      *
      * @param string $directory 
-     * @return void
+     * @return array $loadedTasks
      */
     public function loadTasks($directory = null)
     {

lib/Doctrine/Data.php

@@ -238,7 +238,6 @@ class Doctrine_Data
      * @param string $Doctrine_Record 
      * @param string $fieldName 
      * @return void
-     * @author Jonathan H. Wage
      */
     public function isRelation(Doctrine_Record $record, $fieldName)
     {
@@ -255,4 +254,24 @@ class Doctrine_Data
         
         return false;
     }
+    
+    /**
+     * purge
+     * 
+     * Purge all data for loaded models or for the passed array of Doctrine_Records
+     *
+     * @param string $models 
+     * @return void
+     */
+    public function purge($models = array())
+    {
+        $models = Doctrine::getLoadedModels($models);
+
+        foreach ($models as $model)
+        {
+            $model = new $model();
+
+            $model->getTable()->createQuery()->delete($model)->execute();
+          }
+    }
 }

lib/Doctrine/Import.php

@@ -37,6 +37,7 @@ Doctrine::autoload('Doctrine_Connection_Module');
 class Doctrine_Import extends Doctrine_Connection_Module
 {
     protected $sql = array();
+
     /**
      * lists all databases
      *
@@ -50,6 +51,7 @@ class Doctrine_Import extends Doctrine_Connection_Module
 
         return $this->conn->fetchColumn($this->sql['listDatabases']);
     }
+
     /**
      * lists all availible database functions
      *
@@ -63,6 +65,7 @@ class Doctrine_Import extends Doctrine_Connection_Module
 
         return $this->conn->fetchColumn($this->sql['listFunctions']);
     }
+
     /**
      * lists all database triggers
      *
@@ -73,6 +76,7 @@ class Doctrine_Import extends Doctrine_Connection_Module
     {
         throw new Doctrine_Import_Exception(__FUNCTION__ . ' not supported by this driver.');
     }
+
     /**
      * lists all database sequences
      *
@@ -87,6 +91,7 @@ class Doctrine_Import extends Doctrine_Connection_Module
 
         return $this->conn->fetchColumn($this->sql['listSequences']);
     }
+
     /**
      * lists table constraints
      *
@@ -97,6 +102,7 @@ class Doctrine_Import extends Doctrine_Connection_Module
     {
         throw new Doctrine_Import_Exception(__FUNCTION__ . ' not supported by this driver.');
     }
+
     /**
      * lists table constraints
      *
@@ -107,6 +113,7 @@ class Doctrine_Import extends Doctrine_Connection_Module
     {
         throw new Doctrine_Import_Exception(__FUNCTION__ . ' not supported by this driver.');
     }
+
     /**
      * lists table constraints
      *
@@ -117,6 +124,7 @@ class Doctrine_Import extends Doctrine_Connection_Module
     {
         throw new Doctrine_Import_Exception(__FUNCTION__ . ' not supported by this driver.');
     }
+
     /**
      * lists tables
      *
@@ -127,6 +135,7 @@ class Doctrine_Import extends Doctrine_Connection_Module
     {
         throw new Doctrine_Import_Exception(__FUNCTION__ . ' not supported by this driver.');
     }
+
     /**
      * lists table triggers
      *
@@ -137,6 +146,7 @@ class Doctrine_Import extends Doctrine_Connection_Module
     {
         throw new Doctrine_Import_Exception(__FUNCTION__ . ' not supported by this driver.');
     }
+
     /**
      * lists table views
      *
@@ -147,6 +157,7 @@ class Doctrine_Import extends Doctrine_Connection_Module
     {
         throw new Doctrine_Import_Exception(__FUNCTION__ . ' not supported by this driver.');
     }
+
     /**
      * lists database users
      *
@@ -160,6 +171,7 @@ class Doctrine_Import extends Doctrine_Connection_Module
 
         return $this->conn->fetchColumn($this->sql['listUsers']);
     }
+
     /**
      * lists database views
      *
@@ -174,6 +186,7 @@ class Doctrine_Import extends Doctrine_Connection_Module
 
         return $this->conn->fetchColumn($this->sql['listViews']);
     }
+
     /**
      * importSchema
      *
@@ -187,7 +200,13 @@ class Doctrine_Import extends Doctrine_Connection_Module
     {
         $connections = Doctrine_Manager::getInstance()->getConnections();
         
-        foreach ($connections as $connection) {
+        foreach ($connections as $name => $connection) {
+          // Limit the databases to the ones specified by $databases.
+          // Check only happens if array is not empty
+          if (!empty($databases) && !in_array($name, $databases)) {
+            continue;
+          }
+          
           $builder = new Doctrine_Import_Builder();
           $builder->generateBaseClasses(true);
           $builder->setTargetPath($directory);

lib/Doctrine/Migration.php

@@ -342,6 +342,8 @@ class Doctrine_Migration
         }
         
         $this->setCurrentVersion($to);
+        
+        return true;
     }
     
     /**

lib/Doctrine/Migration/Builder.php

@@ -194,6 +194,8 @@ END;
         }
         
         $this->generateMigrationClass($className, array(), $up, $down);
+        
+        return true;
     }
     
     /**
@@ -243,7 +245,7 @@ END;
      * buildDropTable
      *
      * @param string $tableData 
-     * @return void
+     * @return string
      */
     public function buildDropTable($tableData)
     {
@@ -254,7 +256,7 @@ END;
      * dataToPhpCode
      *
      * @param string $data 
-     * @return void
+     * @return string
      */
     public function dataToPhpCode($data)
     {
@@ -269,7 +271,7 @@ END;
     /**
      * generateMigrationClass
      *
-     * @package default
+     * @return void
      */
     public function generateMigrationClass($className, $options = array(), $up = null, $down = null, $return = false)
     {
@@ -296,7 +298,7 @@ END;
     /**
      * buildMigrationClass
      *
-     * @package default
+     * @return string
      */
     public function buildMigrationClass($className, $fileName = null, $options = array(), $up = null, $down = null)
     {

lib/Doctrine/Task.php

@@ -20,7 +20,9 @@
  */
 
 /**
- * Doctrine_Cli_Task
+ * Doctrine_Task
+ * 
+ * Abstract class used for writing Doctrine Tasks
  *
  * @package     Doctrine
  * @subpackage  Task
@@ -41,6 +43,9 @@ abstract class Doctrine_Task
     /**
      * __construct
      *
+     * Since this is an abstract classes that extend this must follow a patter of Doctrine_Task_{TASK_NAME}
+     * This is what determines the task name for executing it.
+     *
      * @return void
      */
     public function __construct()
@@ -54,7 +59,7 @@ abstract class Doctrine_Task
      * Override with each task class
      *
      * @return void
-     * @author Jonathan H. Wage
+     * @abstract
      */
     abstract function execute();
     
@@ -63,7 +68,7 @@ abstract class Doctrine_Task
      *
      * Validates that all required fields are present
      *
-     * @return void
+     * @return bool true
      */
     public function validate()
     {
@@ -95,7 +100,7 @@ abstract class Doctrine_Task
      *
      * @param string $name 
      * @param string $default 
-     * @return void
+     * @return mixed
      */
     public function getArgument($name, $default = null)
     {
@@ -109,7 +114,7 @@ abstract class Doctrine_Task
     /**
      * getArguments
      *
-     * @return void
+     * @return array $this->arguments
      */
     public function getArguments()
     {
@@ -119,10 +124,10 @@ abstract class Doctrine_Task
     /**
      * setArguments
      *
-     * @param string $args 
+     * @param array $args 
      * @return void
      */
-    public function setArguments($args)
+    public function setArguments(array $args)
     {
         $this->arguments = $args;
     }
@@ -130,7 +135,7 @@ abstract class Doctrine_Task
     /**
      * getTaskName
      *
-     * @return void
+     * @return string $taskName
      */
     public function getTaskName()
     {
@@ -140,7 +145,7 @@ abstract class Doctrine_Task
     /**
      * getDescription
      *
-     * @return void
+     * @return string $description
      */
     public function getDescription()
     {
@@ -150,7 +155,7 @@ abstract class Doctrine_Task
     /**
      * getRequiredArguments
      *
-     * @return void
+     * @return array $requiredArguments
      */
     public function getRequiredArguments()
     {
@@ -160,7 +165,7 @@ abstract class Doctrine_Task
     /**
      * getOptionalArguments
      *
-     * @return void
+     * @return array $optionalArguments
      */
     public function getOptionalArguments()
     {
@@ -170,7 +175,7 @@ abstract class Doctrine_Task
     /**
      * getRequiredArgumentsDescriptions
      *
-     * @return void
+     * @return array $requiredArgumentsDescriptions
      */
     public function getRequiredArgumentsDescriptions()
     {
@@ -180,8 +185,7 @@ abstract class Doctrine_Task
     /**
      * getOptionalArgumentsDescriptions
      *
-     * @return void
+     * @return array $optionalArgumentsDescriptions
-     * @author Jonathan H. Wage
      */
     public function getOptionalArgumentsDescriptions()
     {

sandbox/data/fixtures/contact.yml

@@ -2,7 +2,3 @@
 Contact: 
   Contact_1: 
     name: Jonathan H. Wage
-  Contact_3:
-    name: Daniel Adams
-  Contact_4:
-    name: Robert Adams

sandbox/data/fixtures/user.yml

@@ -1,14 +1,6 @@
 ---
 User: 
   User_1: 
-    username: jwage
+    username: jonwage
-    hair_color: light brown
+    hair_color: brown
     Contact: Contact_1
-  User_2:
-    username: dadams
-    hair_color: dark brown
-    Contact: Contact_3
-  User_3:
-    username: radams
-    hair_color: light brown
-    Contact: Contact_4