- improved phpdoc

library/Solarium/Client.php

@@ -74,9 +74,12 @@ class Solarium_Client extends Solarium_Configurable
     /**
      * Adapter instance
      *
-     * The adapter is lazy-loading, it will be instantiated on first use by
-     * {@link getAdapter()} based on the 'adapter' entry in {@link $_options}.
-     * This option can be set using {@link setAdapter()}
+     * If an adapter instance is set using {@link setAdapter()} this var will
+     * contain a reference to that instance.
+     *
+     * In all other cases the adapter is lazy-loading, it will be instantiated
+     * on first use by {@link getAdapter()} based on the 'adapter' entry in
+     * {@link $_options}. This option can be set using {@link setAdapter()}
      *
      * @var Solarium_Client_Adapter
      */

library/Solarium/Configurable.php

@@ -35,8 +35,13 @@
  */
 
 /**
- * Base class for creating a class that is configurable using the constructor or
- * setOption calls. Used by many solarium classes.
+ * Base class for configurable classes
+ *
+ * All classes extending this class are  configurable using the constructor or
+ * setOption calls. This is the base for many Solarium classes, providing a
+ * uniform interface for various models.
+ *
+ * @package Solarium
  */
 class Solarium_Configurable
 {
@@ -52,6 +57,15 @@ class Solarium_Configurable
     /**
      * Constructor
      *
+     * If options are passed they will be merged with {@link $_options}, with
+     * new values overwriting any existing (default) values.
+     *
+     * If $options is an object it will be converted into an array by called
+     * it's toArray method. This is compatible with the Zend_Config classes in
+     * Zend Framework, but can also easily be implemented in any other object.
+     *
+     * After handling the options the {@link _init()} method is called.
+     *
      * @throws Solarium_Exception
      * @param array|Zend_Config $options
      * @return void
@@ -69,11 +83,10 @@ class Solarium_Configurable
                 }
             }
 
-            // merge with default values, new values overwrite defaults
             $this->_options = array_merge($this->_options, $options);
         }
 
-        // Hook for extending classes (for end user classes)
+
         $this->_init();
     }
 
@@ -87,6 +100,10 @@ class Solarium_Configurable
      * This hook is called by the constructor after saving the constructor
      * arguments in {@link $_options}
      *
+     * @internal This empty implementation can optionally be implemented in
+     *  descending classes. It's not an abstract method on purpose, there are
+     *  many cases where no initialization is needed.
+     *
      * @return void
      */
     protected function _init()
@@ -111,6 +128,8 @@ class Solarium_Configurable
     /**
      * Get an option value
      *
+     * If the options is empty or not set a NULL value will be returned.
+     *
      * @param string $name
      * @return mixed
      */

library/Solarium/Exception.php

@@ -35,7 +35,12 @@
  */
 
 /**
- * Custom exception case to allow for catching specific exceptions
+ * Solarium specific exception
+ *
+ * All exceptions thrown by Solarium are of this type. This way you can easily
+ * catch Solarium exception and keep them separate from you own exceptions.
+ *
+ * @package Solarium
  */
 class Solarium_Exception extends Exception
 {

library/Solarium/Version.php

@@ -35,14 +35,20 @@
  */
 
 /**
- * This class can be used to check the library version within your code.
- * For example to check for a required version.
+ * Version indicator
+ *
+ * This class can be used to check the library version within your code. This
+ * can be important if you rely on a minimal version for the features you use.
+ *
+ * @package Solarium
  */
 class Solarium_Version
 {
 
     /**
-     * Version number
+     * Version number of the Solarium library
+     * 
+     * @var string
      */
     const VERSION = '0.1-dev';