minor refactorings on code and API docs

lib/Doctrine/DBAL/Driver/PDOConnection.php

 <?php
 
+/**
+ * PDO implementation of the driver Connection interface.
+ * Used by all PDO-based drivers.
+ *
+ * @since 2.0
+ */
 class Doctrine_DBAL_Driver_PDOConnection extends PDO implements Doctrine_DBAL_Driver_Connection
 {
     public function __construct($dsn, $user = null, $password = null, array $options = null)
     {
         parent::__construct($dsn, $user, $password, $options);
         $this->setAttribute(PDO::ATTR_STATEMENT_CLASS, array('Doctrine_DBAL_Driver_PDOStatement', array()));
+        $this->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
+        $this->setAttribute(PDO::ATTR_CASE, PDO::CASE_LOWER);
     }
 }
 

lib/Doctrine/DBAL/Driver/PDOSqlite/Driver.php

@@ -4,9 +4,22 @@
 
 #use Doctrine::DBAL::Driver;
 
+/**
+ * The PDO Sqlite driver.
+ *
+ * @since 2.0
+ */
 class Doctrine_DBAL_Driver_PDOSqlite_Driver implements Doctrine_DBAL_Driver
 {
-    
+    /**
+     * Tries to establish a database connection to SQLite.
+     *
+     * @param array $params
+     * @param unknown_type $username
+     * @param unknown_type $password
+     * @param array $driverOptions
+     * @return unknown
+     */
     public function connect(array $params, $username = null, $password = null, array $driverOptions = array())
     {
         return new Doctrine_DBAL_Driver_PDOConnection(
@@ -34,11 +47,20 @@ class Doctrine_DBAL_Driver_PDOSqlite_Driver implements Doctrine_DBAL_Driver
         return $dsn;
     }
     
+    /**
+     * Gets the database platform that is relevant for this driver.
+     */
     public function getDatabasePlatform()
     {
         return new Doctrine_DBAL_Platforms_SqlitePlatform();
     }
     
+    /**
+     * Gets the schema manager that is relevant for this driver.
+     *
+     * @param Doctrine::DBAL::Connection $conn
+     * @return Doctrine::DBAL::Schema::AbstractSchemaManager
+     */
     public function getSchemaManager(Doctrine_DBAL_Connection $conn)
     {
         return new Doctrine_DBAL_Schema_SqliteSchemaManager($conn);

lib/Doctrine/DBAL/DriverManager.php

@@ -22,19 +22,19 @@
 #namespace Doctrine::DBAL;
 
 /**
- * Factory for creating dbms-specific Connection instances.
+ * Factory for creating Doctrine::DBAL::Connection instances.
  *
  * @author Roman Borschel <roman@code-factory.org>
  * @since 2.0
  */
-class Doctrine_DBAL_DriverManager
+final class Doctrine_DBAL_DriverManager
 {
     /**
      * List of supported drivers and their mappings to the driver class.
      *
      * @var array
      */
-     private $_drivers = array(
+     private static $_driverMap = array(
             'pdo_mysql'  => 'Doctrine_DBAL_Driver_PDOMySql_Driver',
             'pdo_sqlite' => 'Doctrine_DBAL_Driver_PDOSqlite_Driver',
             'pdo_pgsql'  => 'Doctrine_DBAL_Driver_PDOPgSql_Driver',
@@ -44,18 +44,53 @@ class Doctrine_DBAL_DriverManager
             'pdo_informix' => 'Doctrine_DBAL_Driver_PDOInformix_Driver',
             );
     
-    public function __construct()
-    {
-        
-    }
+    private function __construct() {}
             
     /**
-     * Creates a connection object with the specified parameters.
+     * Creates a connection object based on the specified parameters.
+     * This method returns a Doctrine::DBAL::Connection which wraps the underlying
+     * driver connection.
      *
-     * @param array $params
-     * @return Connection
+     * $params must contain at least one of the following.
+     * 
+     * Either 'driver' with one of the following values:
+     *     pdo_mysql
+     *     pdo_sqlite
+     *     pdo_pgsql
+     *     pdo_oracle
+     *     pdo_mssql
+     *     pdo_firebird
+     *     pdo_informix
+     * 
+     * OR 'driverClass' that contains the full class name (with namespace) of the
+     * driver class to instantiate.
+     * 
+     * Other (optional) parameters:
+     * 
+     * <b>user (string)</b>:
+     * The username to use when connecting. 
+     * 
+     * <b>password (string)</b>:
+     * The password to use when connecting.
+     * 
+     * <b>driverOptions (array)</b>:
+     * Any additional driver-specific options for the driver. These are just passed
+     * through to the driver.
+     * 
+     * <b>pdo</b>:
+     * You can pass an existing PDO instance through this parameter. The PDO
+     * instance will be wrapped in a Doctrine::DBAL::Connection.
+     * 
+     * <b>wrapperClass</b>:
+     * You may specify a custom wrapper class through the 'wrapperClass'
+     * parameter but this class MUST inherit from Doctrine::DBAL::Connection.
+     * 
+     * @param array $params The parameters.
+     * @param Doctrine::Common::Configuration The configuration to use.
+     * @param Doctrine::Common::EventManager The event manager to use.
+     * @return Doctrine::DBAL::Connection
      */
-    public function getConnection(array $params, Doctrine_Common_Configuration $config = null,
+    public static function getConnection(array $params, Doctrine_Common_Configuration $config = null,
             Doctrine_Common_EventManager $eventManager = null)
     {
         // create default config and event manager, if not set
@@ -72,18 +107,18 @@ class Doctrine_DBAL_DriverManager
         } else if (isset($params['pdo'])) {
             $params['driver'] = $params['pdo']->getAttribute(PDO::ATTR_DRIVER_NAME);
         } else {
-            $this->_checkParams($params);
+            self::_checkParams($params);
         }
         if (isset($params['driverClass'])) {
             $className = $params['driverClass'];
         } else {
-            $className = $this->_drivers[$params['driver']];
+            $className = self::$_driverMap[$params['driver']];
         }
         
         $driver = new $className();
         
         $wrapperClass = 'Doctrine_DBAL_Connection';
-        if (isset($params['wrapperClass'])) {
+        if (isset($params['wrapperClass']) && is_subclass_of($params['wrapperClass'], $wrapperClass)) {
             $wrapperClass = $params['wrapperClass'];
         }
         
@@ -95,7 +130,7 @@ class Doctrine_DBAL_DriverManager
      *
      * @param array $params
      */
-    private function _checkParams(array $params)
+    private static function _checkParams(array $params)
     {        
         // check existance of mandatory parameters
         
@@ -107,7 +142,7 @@ class Doctrine_DBAL_DriverManager
         // check validity of parameters
         
         // driver
-        if ( isset($params['driver']) && ! isset($this->_drivers[$params['driver']])) {
+        if ( isset($params['driver']) && ! isset(self::$_driverMap[$params['driver']])) {
             throw Doctrine_DBAL_Exceptions_DBALException::unknownDriver($params['driver']);
         }
     }

lib/Doctrine/ORM/EntityManager.php

@@ -23,8 +23,7 @@
 
 #use Doctrine::Common::Configuration;
 #use Doctrine::Common::EventManager;
-#use Doctrine::Common::NullObject;
-#use Doctrine::DBAL::Connections::Connection;
+#use Doctrine::DBAL::Connection;
 #use Doctrine::ORM::Exceptions::EntityManagerException;
 #use Doctrine::ORM::Internal::UnitOfWork;
 #use Doctrine::ORM::Mapping::ClassMetadata;
@@ -355,6 +354,12 @@ class Doctrine_ORM_EntityManager
         $this->_flushMode = $flushMode;
     }
     
+    /**
+     * Checks whether the given value is a valid flush mode.
+     *
+     * @param string $value
+     * @return boolean
+     */
     private function _isFlushMode($value)
     {
         return $value == self::FLUSHMODE_AUTO ||
@@ -397,34 +402,6 @@ class Doctrine_ORM_EntityManager
         $this->_closed = true;
     }
     
-    /**
-     * Gets the result cache driver used by the EntityManager.
-     *
-     * @return Doctrine::ORM::Cache::CacheDriver The cache driver.
-     */
-    public function getResultCacheDriver()
-    {
-        if ( ! $this->getAttribute(Doctrine::ATTR_RESULT_CACHE)) {
-            throw new Doctrine_Exception('Result Cache driver not initialized.');
-        }
-        
-        return $this->getAttribute(Doctrine::ATTR_RESULT_CACHE);
-    }
-
-    /**
-     * getQueryCacheDriver
-     *
-     * @return Doctrine_Cache_Interface
-     */
-    public function getQueryCacheDriver()
-    {
-        if ( ! $this->getAttribute(Doctrine::ATTR_QUERY_CACHE)) {
-            throw new Doctrine_Exception('Query Cache driver not initialized.');
-        }
-        
-        return $this->getAttribute(Doctrine::ATTR_QUERY_CACHE);
-    }
-    
     /**
      * Saves the given entity, persisting it's state.
      * 
@@ -649,6 +626,9 @@ class Doctrine_ORM_EntityManager
         return $this->_config;
     }
     
+    /**
+     * Throws an exception if the EntityManager is closed or currently not active.
+     */
     private function _errorIfNotActiveOrClosed()
     {
         if ( ! $this->isActive() || $this->_closed) {
@@ -702,9 +682,8 @@ class Doctrine_ORM_EntityManager
             Doctrine_Common_EventManager $eventManager = null)
     {
         if (is_array($conn)) {
-            $connFactory = new Doctrine_DBAL_DriverManager();
-            $conn = $connFactory->getConnection($conn, $config, $eventManager);
-        } else if ( ! $conn instanceof Doctrine_Connection) {
+            $conn = Doctrine_DBAL_DriverManager::getConnection($conn, $config, $eventManager);
+        } else if ( ! $conn instanceof Doctrine_DBAL_Connection) {
             throw new Doctrine_Exception("Invalid parameter '$conn'.");
         }
         
@@ -722,7 +701,9 @@ class Doctrine_ORM_EntityManager
     }
     
     /**
-     * Gets the currently active EntityManager.
+     * Static lookup to get the currently active EntityManager.
+     * This is used in the Entity constructor as well as unserialize() to connect
+     * the Entity with an EntityManager.
      *
      * @return Doctrine::ORM::EntityManager
      */

lib/Doctrine/ORM/Internal/CommitOrderCalculator.php

@@ -26,7 +26,6 @@
  * correct order in which changes to entities need to be persisted.
  *
  * @since 2.0
- * @todo Rename to: CommitOrderCalculator
  * @author Roman Borschel <roman@code-factory.org> 
  */
 class Doctrine_ORM_Internal_CommitOrderCalculator
@@ -88,16 +87,34 @@ class Doctrine_ORM_Internal_CommitOrderCalculator
         return $this->_sorted;
     }
     
+    /**
+     * Adds a node to consider when ordering.
+     *
+     * @param mixed $key Somme arbitrary key for the node (must be unique!).
+     * @param unknown_type $node
+     */
     public function addNode($key, $node)
     {
         $this->_nodes[$key] = $node;
     }
     
+    /**
+     * Enter description here...
+     *
+     * @param unknown_type $key
+     * @param unknown_type $item
+     */
     public function addNodeWithItem($key, $item)
     {
         $this->_nodes[$key] = new Doctrine_ORM_Internal_CommitOrderNode($item, $this);
     }
     
+    /**
+     * Enter description here...
+     *
+     * @param unknown_type $key
+     * @return unknown
+     */
     public function getNodeForKey($key)
     {
         return $this->_nodes[$key];
@@ -108,13 +125,17 @@ class Doctrine_ORM_Internal_CommitOrderCalculator
         return isset($this->_nodes[$key]);
     }
     
+    /**
+     * Clears the current graph and the last result.
+     *
+     * @return void
+     */
     public function clear()
     {
         $this->_nodes = array();
         $this->_sorted = array();
     }
     
-    
     public function getNextTime()
     {
         return ++$this->_currentTime;

lib/Doctrine/ORM/Internal/CommitOrderNode.php

@@ -22,7 +22,7 @@
 #namespace Doctrine::ORM::Internal;
 
 /**
- * A CommitOrderNode is a temporary wrapper around ClassMetadata objects
+ * A CommitOrderNode is a temporary wrapper around ClassMetadata instances
  * that is used to sort the order of commits.
  * 
  * @since 2.0
@@ -40,19 +40,32 @@ class Doctrine_ORM_Internal_CommitOrderNode
     private $_calculator;
     private $_relatedNodes = array();
     
+    /* The "time" when this node was first discovered during traversal */
     private $_discoveryTime;
+    /* The "time" when this node was finished during traversal */
     private $_finishingTime;
     
+    /* The wrapped object */
     private $_wrappedObj;
-    private $_relationEdges = array();
-    
     
+    /**
+     * Constructor.
+     * Creates a new node.
+     *
+     * @param mixed $wrappedObj The object to wrap.
+     * @param Doctrine::ORM::Internal::CommitOrderCalculator $calc The calculator.
+     */
     public function __construct($wrappedObj, Doctrine_ORM_Internal_CommitOrderCalculator $calc)
     {
         $this->_wrappedObj = $wrappedObj;
         $this->_calculator = $calc;
     }
     
+    /**
+     * Gets the wrapped object.
+     *
+     * @return mixed
+     */
     public function getClass()
     {
         return $this->_wrappedObj;
@@ -142,7 +155,7 @@ class Doctrine_ORM_Internal_CommitOrderNode
     /**
      * Adds a directed dependency (an edge on the graph). "$this -before-> $other".
      *
-     * @param Doctrine_Internal_CommitOrderNode $node
+     * @param Doctrine::ORM::Internal::CommitOrderNode $node
      */
     public function before(Doctrine_ORM_Internal_CommitOrderNode $node)
     {

lib/Doctrine/ORM/Internal/Hydration/AbstractHydrator.php

@@ -62,9 +62,9 @@ abstract class Doctrine_ORM_Internal_Hydration_AbstractHydrator
 
 
     /**
-     * constructor
+     * Constructor.
      *
-     * @param Doctrine_Connection|null $connection
+     * @param Doctrine::ORM::EntityManager $em The EntityManager to use during hydration.
      */
     public function __construct(Doctrine_ORM_EntityManager $em)
     {
@@ -134,20 +134,14 @@ abstract class Doctrine_ORM_Internal_Hydration_AbstractHydrator
     }
 
     /**
-     * hydrateResultSet
-     *
      * Processes data returned by statement object.
      *
-     * This is method defines the core of Doctrine object population algorithm
-     * hence this method strives to be as fast as possible.
-     *
-     * The key idea is the loop over the rowset only once doing all the needed operations
-     * within this massive loop.
+     * This is method defines the core of Doctrine object/array population algorithm.
      *
      * @param mixed $stmt PDOStatement
      * @param integer $hydrationMode Doctrine processing mode to be used during hydration process.
      *                               One of the Doctrine::HYDRATE_* constants.
-     * @return mixed Doctrine_Collection|array
+     * @return mixed
      */
     abstract public function hydrateResultSet($parserResult);
 }

lib/Doctrine/ORM/Internal/Hydration/ArrayDriver.php

@@ -126,7 +126,6 @@ class Doctrine_ORM_Internal_Hydration_ArrayDriver
     public function getLastKey(&$data)
     {
         end($data);
-        
         return key($data);
     }
     

lib/Doctrine/ORM/Internal/Hydration/ObjectDriver.php

@@ -19,6 +19,8 @@
  * <http://www.phpdoctrine.org>.
  */
 
+#namespace Doctrine::ORM::Internal::Hydration;
+
 /**
  * Hydration strategy used for creating graphs of entities.
  *
@@ -28,7 +30,6 @@
  * @version     $Revision$
  * @author      Konsta Vesterinen <kvesteri@cc.hut.fi>
  * @author      Roman Borschel <roman@code-factory.org>
- * @todo Rename to ObjectDriver
  */
 class Doctrine_ORM_Internal_Hydration_ObjectDriver
 {

tests/lib/Doctrine_TestUtil.php

@@ -4,8 +4,6 @@ class Doctrine_TestUtil
 {    
     public static function getConnection()
     {
-        $connFactory = new Doctrine_DBAL_DriverManager();
-        
         if (isset($GLOBALS['db_type'], $GLOBALS['db_username'], $GLOBALS['db_password'],
                 $GLOBALS['db_host'], $GLOBALS['db_name'])) {
             $params = array(
@@ -24,7 +22,7 @@ class Doctrine_TestUtil
             );
         }
         
-        return $connFactory->getConnection($params);
+        return Doctrine_DBAL_DriverManager::getConnection($params);
     }
     /*
     public static function autoloadModel($className)