diff --git a/lib/Doctrine/Db.php b/lib/Doctrine/Db.php
index 4a3753e38..0ca904ee4 100644
--- a/lib/Doctrine/Db.php
+++ b/lib/Doctrine/Db.php
@@ -22,20 +22,32 @@
  * Doctrine_Db
  * A thin wrapper layer on top of PDO / Doctrine_Adapter
  *
- * The purpose of this class is to provide an easy to use, pluggable eventlistener
- * architecture to database handler object
+ * Doctrine_Db provides the following things to underlying database hanlder
  *
- * Aspects such as logging, query profiling and caching can be easily implemented through
- * the use of these listeners
+ * 1. Event listeners
+ *    An easy to use, pluggable eventlistener architecture. Aspects such as
+ *    logging, query profiling and caching can be easily implemented through
+ *    the use of these listeners
  *
- * @author      Konsta Vesterinen <kvesteri@cc.hut.fi>
- * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
- * @package     Doctrine
- * @category    Object Relational Mapping
- * @link        www.phpdoctrine.com
- * @since       1.0
- * @version     $Revision$
- */
+ * 2. Lazy-connecting
+ *    Creating an instance of Doctrine_Db does not connect
+ *    to database. Connecting to database is only invoked when actually needed
+ *    (for example when query() is being called)
+ *
+ * 3. Portable error codes
+ *    Doctrine_Db_Exception drivers provide portable error code handling.
+ *
+ * 4. Easy-to-use fetching methods
+ *    For convience Doctrine_Db provides methods such as fetchOne(), fetchAssoc() etc.
+ *
+ * @author      Konsta Vesterinen <kvesteri@cc.hut.fi>
+ * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @package     Doctrine
+ * @category    Object Relational Mapping
+ * @link        www.phpdoctrine.com
+ * @since       1.0
+ * @version     $Revision$
+ */
 class Doctrine_Db implements Countable, IteratorAggregate, Doctrine_Adapter_Interface {
     /**
      * error constants
@@ -401,29 +413,70 @@ class Doctrine_Db implements Countable, IteratorAggregate, Doctrine_Adapter_Inte
     /**
      * fetchAll
      *
+     * @param string $statement         sql query to be executed
+     * @param array $params             prepared statement params
      * @return array
      */
     public function fetchAll($statement, array $params = array()) {
         return $this->query($statement, $params)->fetchAll(PDO::FETCH_ASSOC);
     }
-
+    /**
+     * fetchOne
+     *
+     * @param string $statement         sql query to be executed
+     * @param array $params             prepared statement params
+     * @return mixed
+     */
     public function fetchOne($statement, array $params = array()) {
         return current($this->query($statement, $params)->fetch(PDO::FETCH_NUM));
     }
-    
+    /**
+     * fetchRow
+     *
+     * @param string $statement         sql query to be executed
+     * @param array $params             prepared statement params
+     * @return array
+     */
     public function fetchRow($statement, array $params = array()) {
         return $this->query($statement, $params)->fetch(PDO::FETCH_ASSOC);
     }
-    
+    /**
+     * fetchArray
+     *
+     * @param string $statement         sql query to be executed
+     * @param array $params             prepared statement params
+     * @return array
+     */
     public function fetchArray($statement, array $params = array()) {
         return $this->query($statement, $params)->fetch(PDO::FETCH_NUM);
     }
+    /**
+     * fetchColumn
+     *
+     * @param string $statement         sql query to be executed
+     * @param array $params             prepared statement params
+     * @return array
+     */
     public function fetchColumn($statement, array $params = array()) {
         return $this->query($statement, $params)->fetchAll(PDO::FETCH_COLUMN);
     }
+    /**
+     * fetchAssoc
+     *
+     * @param string $statement         sql query to be executed
+     * @param array $params             prepared statement params
+     * @return array
+     */
     public function fetchAssoc($statement, array $params = array()) {
         return $this->query($statement, $params)->fetchAll(PDO::FETCH_ASSOC);
     }
+    /**
+     * fetchBoth
+     *
+     * @param string $statement         sql query to be executed
+     * @param array $params             prepared statement params
+     * @return array
+     */
     public function fetchBoth($statement, array $params = array()) { 
         return $this->query($statement, $params)->fetchAll(PDO::FETCH_BOTH);
     }