[phpdoc] Add API documentation.

This is a starting point to add a documentation of the whole set of APIs and
classes of Predis. The next step will be to actually improve and extend it.

lib/Predis/ConnectionFactory.php

@@ -13,12 +13,22 @@ namespace Predis;
 
 use Predis\Network\IConnectionSingle;
 
+/**
+ * Provides a default factory for Redis connections that maps URI schemes
+ * to connection classes implementing the Predis\Network\IConnectionSingle
+ * interface.
+ *
+ * @author Daniele Alessandri <suppakilla@gmail.com>
+ */
 class ConnectionFactory implements IConnectionFactory
 {
     private static $_globalSchemes;
 
     private $_instanceSchemes = array();
 
+    /**
+     * @param array $schemesMap Map of URI schemes to connection classes.
+     */
     public function __construct(Array $schemesMap = null)
     {
         $this->_instanceSchemes = self::ensureDefaultSchemes();
@@ -30,6 +40,13 @@ class ConnectionFactory implements IConnectionFactory
         }
     }
 
+    /**
+     * Checks if the provided argument represents a valid connection class
+     * implementing the Predis\Network\IConnectionSingle interface. Optionally,
+     * callable objects are used for lazy initialization of connection objects.
+     *
+     * @param mixed $initializer FQN of a connection class or a callable for lazy initialization.
+     */
     private static function checkConnectionInitializer($initializer)
     {
         if (is_callable($initializer)) {
@@ -45,6 +62,11 @@ class ConnectionFactory implements IConnectionFactory
         }
     }
 
+    /**
+     * Ensures that the default global URI schemes map is initialized.
+     *
+     * @return array
+     */
     private static function ensureDefaultSchemes()
     {
         if (!isset(self::$_globalSchemes)) {
@@ -57,6 +79,12 @@ class ConnectionFactory implements IConnectionFactory
         return self::$_globalSchemes;
     }
 
+    /**
+     * Defines a new URI scheme => connection class relation at class level.
+     *
+     * @param string $scheme URI scheme
+     * @param mixed $connectionInitializer FQN of a connection class or a callable for lazy initialization.
+     */
     public static function define($scheme, $connectionInitializer)
     {
         self::ensureDefaultSchemes();
@@ -64,12 +92,21 @@ class ConnectionFactory implements IConnectionFactory
         self::$_globalSchemes[$scheme] = $connectionInitializer;
     }
 
+    /**
+     * Defines a new URI scheme => connection class relation at instance level.
+     *
+     * @param string $scheme URI scheme
+     * @param mixed $connectionInitializer FQN of a connection class or a callable for lazy initialization.
+     */
     public function defineConnection($scheme, $connectionInitializer)
     {
         self::checkConnectionInitializer($connectionInitializer);
         $this->_instanceSchemes[$scheme] = $connectionInitializer;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function create($parameters)
     {
         if (!$parameters instanceof IConnectionParameters) {