* renamed some files libs

* added doc comments to drivers
* DibiDriver::prepare() renamed to config()
* fixed connection error handling in Postgre driver

dibi/drivers/pdo.php

@@ -27,6 +27,10 @@
  */
 class DibiPdoDriver extends DibiDriver
 {
+    /**
+     * Describes how convert some datatypes to SQL command
+     * @var array
+     */
     public $formats = array(
         'TRUE'     => "1",
         'FALSE'    => "0",
@@ -35,21 +39,28 @@ class DibiPdoDriver extends DibiDriver
     );
 
 
-
     /**
+     * Creates object and (optionally) connects to a database
+     *
      * @param array  connect configuration
      * @throws DibiException
      */
-    public function __construct($config)
+    public function __construct(array $config)
     {
-        self::prepare($config, 'username', 'user');
-        self::prepare($config, 'password', 'pass');
-        self::prepare($config, 'dsn');
+        self::config($config, 'username', 'user');
+        self::config($config, 'password', 'pass');
+        self::config($config, 'dsn');
         parent::__construct($config);
     }
 
 
 
+    /**
+     * Connects to a database
+     *
+     * @throws DibiException
+     * @return resource
+     */
     protected function connect()
     {
         if (!extension_loaded('pdo')) {
@@ -66,6 +77,13 @@ class DibiPdoDriver extends DibiDriver
 
 
 
+    /**
+     * Internal: Executes the SQL query
+     *
+     * @param string       SQL statement.
+     * @return DibiResult|TRUE  Result set object
+     * @throws DibiDatabaseException
+     */
     protected function doQuery($sql)
     {
         $res = $this->getConnection()->query($sql);
@@ -74,6 +92,11 @@ class DibiPdoDriver extends DibiDriver
 
 
 
+    /**
+     * Gets the number of affected rows by the last INSERT, UPDATE or DELETE query
+     *
+     * @return int       number of rows or FALSE on error
+     */
     public function affectedRows()
     {
         throw new BadMethodCallException(__METHOD__ . ' is not implemented');
@@ -81,6 +104,11 @@ class DibiPdoDriver extends DibiDriver
 
 
 
+    /**
+     * Retrieves the ID generated for an AUTO_INCREMENT column by the previous INSERT query
+     *
+     * @return int|FALSE  int on success or FALSE on failure
+     */
     public function insertId()
     {
         return $this->getConnection()->lastInsertId();
@@ -88,6 +116,10 @@ class DibiPdoDriver extends DibiDriver
 
 
 
+    /**
+     * Begins a transaction (if supported).
+     * @return void
+     */
     public function begin()
     {
         $this->getConnection()->beginTransaction();
@@ -96,6 +128,10 @@ class DibiPdoDriver extends DibiDriver
 
 
 
+    /**
+     * Commits statements in a transaction.
+     * @return void
+     */
     public function commit()
     {
         $this->getConnection()->commit();
@@ -104,6 +140,10 @@ class DibiPdoDriver extends DibiDriver
 
 
 
+    /**
+     * Rollback changes in a transaction.
+     * @return void
+     */
     public function rollback()
     {
         $this->getConnection()->rollBack();
@@ -112,6 +152,11 @@ class DibiPdoDriver extends DibiDriver
 
 
 
+    /**
+     * Returns last error
+     *
+     * @return array with items 'message' and 'code'
+     */
     public function errorInfo()
     {
         $error = $this->getConnection()->errorInfo();
@@ -124,6 +169,13 @@ class DibiPdoDriver extends DibiDriver
 
 
 
+    /**
+     * Escapes the string
+     *
+     * @param string     unescaped string
+     * @param bool       quote string?
+     * @return string    escaped and optionally quoted string
+     */
     public function escape($value, $appendQuotes = TRUE)
     {
         if (!$appendQuotes) {
@@ -134,6 +186,12 @@ class DibiPdoDriver extends DibiDriver
 
 
 
+    /**
+     * Delimites identifier (table's or column's name, etc.)
+     *
+     * @param string     identifier
+     * @return string    delimited identifier
+     */
     public function delimite($value)
     {
         // quoting is not supported by PDO
@@ -142,6 +200,11 @@ class DibiPdoDriver extends DibiDriver
 
 
 
+    /**
+     * Gets a information of the current database.
+     *
+     * @return DibiMetaData
+     */
     public function getMetaData()
     {
         throw new BadMethodCallException(__METHOD__ . ' is not implemented');
@@ -150,7 +213,12 @@ class DibiPdoDriver extends DibiDriver
 
 
     /**
-     * @see DibiDriver::applyLimit()
+     * Injects LIMIT/OFFSET to the SQL query
+     *
+     * @param string &$sql  The SQL query that will be modified.
+     * @param int $limit
+     * @param int $offset
+     * @return void
      */
     public function applyLimit(&$sql, $limit, $offset = 0)
     {
@@ -172,6 +240,11 @@ class DibiPdoResult extends DibiResult
     private $row = 0;
 
 
+    /**
+     * Returns the number of rows in a result set
+     *
+     * @return int
+     */
     public function rowCount()
     {
         return $this->resource->rowCount();
@@ -179,6 +252,12 @@ class DibiPdoResult extends DibiResult
 
 
 
+    /**
+     * Fetches the row at current position and moves the internal cursor to the next position
+     * internal usage only
+     *
+     * @return array|FALSE  array on success, FALSE if no next record
+     */
     protected function doFetch()
     {
         return $this->resource->fetch(PDO::FETCH_ASSOC, PDO::FETCH_ORI_NEXT, $this->row++);
@@ -186,6 +265,12 @@ class DibiPdoResult extends DibiResult
 
 
 
+    /**
+     * Moves cursor position without fetching row
+     *
+     * @param  int      the 0-based cursor pos to seek to
+     * @return boolean  TRUE on success, FALSE if unable to seek to specified record
+     */
     public function seek($row)
     {
         $this->row = $row;
@@ -193,6 +278,11 @@ class DibiPdoResult extends DibiResult
 
 
 
+    /**
+     * Frees the resources allocated for this result set
+     *
+     * @return void
+     */
     protected function free()
     {
     }