- many phpdoc improvements

library/Solarium/Client/Adapter.php

@@ -37,6 +37,22 @@
 
 /**
  * Base class for all adapters
+ *
+ * The goal of an adapter is to accept a query, execute it and return the right
+ * result object. This is actually quite a complex task as it involves the
+ * handling of all Solr communication.
+ *
+ * The adapter structure allows for varying implementations of this task.
+ *
+ * Most adapters will use some sort of HTTP client. In that case the
+ * Solarium_Client_Request request builders and Solarium_Client_Response
+ * response parsers can be used to simplify HTTP communication.
+ * See {@link Solarium_Client_Adapter_Http} as an example.
+ *
+ * However an adapter may also implement all logic by itself if needed.
+ *
+ * @package Solarium
+ * @subpackage Client
  */
 abstract class Solarium_Client_Adapter extends Solarium_Configurable
 {
@@ -53,7 +69,9 @@ abstract class Solarium_Client_Adapter extends Solarium_Configurable
     );
 
     /**
-     * Set options (overrides any existing values)
+     * Set options
+     *
+     * Overrides any existing values
      *
      * @param array $options
      * @return void
@@ -64,6 +82,8 @@ abstract class Solarium_Client_Adapter extends Solarium_Configurable
     }
 
     /**
+     * Execute a select query
+     *
      * Abstract method to require an implementation inside all adapters.
      * If the adapter cannot support this method it should implement a method
      * that throws an exception.
@@ -75,6 +95,8 @@ abstract class Solarium_Client_Adapter extends Solarium_Configurable
     abstract public function select($query);
 
     /**
+     * Execute a ping query
+     *
      * Abstract method to require an implementation inside all adapters.
      * If the adapter cannot support this method it should implement a method
      * that throws an exception.
@@ -86,6 +108,8 @@ abstract class Solarium_Client_Adapter extends Solarium_Configurable
     abstract public function ping($query);
 
     /**
+     * Execute an update query
+     *
      * Abstract method to require an implementation inside all adapters.
      * If the adapter cannot support this method it should implement a method
      * that throws an exception.

library/Solarium/Client/Adapter/Http.php

@@ -36,7 +36,10 @@
  */
 
 /**
- * A very basic adapter using file_get_contents for retrieving data from Solr
+ * Basic HTTP adapter using a stream
+ *
+ * @package Solarium
+ * @subpackage Client
  */
 class Solarium_Client_Adapter_Http extends Solarium_Client_Adapter
 {
@@ -96,7 +99,6 @@ class Solarium_Client_Adapter_Http extends Solarium_Client_Adapter
     /**
      * Handle Solr communication
      *
-     * @todo implement timeout
      * @todo check http response code
      *
      * @throws Solarium_Exception
@@ -146,13 +148,12 @@ class Solarium_Client_Adapter_Http extends Solarium_Client_Adapter
         }
     }
 
-
     /**
-     * TODO
+     * Decode json response data
      * 
      * @throws Solarium_Exception
-     * @param  $data
-     * @return mixed
+     * @param string $data
+     * @return string
      */
     protected function _jsonDecode($data)
     {

library/Solarium/Client/Adapter/ZendHttp.php

@@ -36,7 +36,7 @@
  */
 
 /**
- * An adapter that uses a Zend_Http_Client for Solr request
+ * Adapter that uses a Zend_Http_Client
  *
  * The Zend Framework HTTP client has many great features and has lots of
  * configuration options. For more info see the manual at
@@ -56,7 +56,9 @@ class Solarium_Client_Adapter_ZendHttp extends Solarium_Client_Adapter_Http
     protected $_zendHttp;
 
     /**
-     * Set options (overrides any existing values)
+     * Set options
+     *
+     * Overrides any existing values.
      * 
      * If the options array has an 'adapteroptions' entry it is forwarded to the
      * Zend_Http_Client. See the Zend_Http_Clientdocs for the many config

library/Solarium/Client/Request.php

@@ -36,7 +36,16 @@
  */
 
 /**
+ * Base class for building Solr HTTP requests
  *
+ * Most {@link Solarium_Client_Adapter} implementations will use HTTP for
+ * communicating with Solr. While the HTTP part is adapter-specific, generating
+ * the HTTP request setting (url, postdata, etc.) is not.
+ * This abstract class is the base for several requestbuilders that generate the
+ * settings for the various querytypes.
+ *
+ * @package Solarium
+ * @subpackage Client
  */
 abstract class Solarium_Client_Request
 {
@@ -48,30 +57,37 @@ abstract class Solarium_Client_Request
     const HEAD    = 'HEAD';
 
     /**
-     * TODO
+     * Query instance
+     *
+     * The query that has to be used for building the request.
      *
      * @var Solarium_Query
      */
     protected $_query;
 
     /**
-     * TODO
+     * Adapter options
+     *
+     * When the adapter class the {@link __construct()} method it forwards it's
+     * options. These options are needed for building the right uri.
      *
      * @var array
      */
     protected $_options;
 
     /**
-     * TODO
+     * HTTP GET params
+     *
+     * Used for building the uri in {@link buildUri()}
      * 
      * @var array
      */
     protected $_params;
 
     /**
-     * TODO
+     * Constructor
      *
-     * @param array|object $options
+     * @param array|object $options Passed on by the adapter
      * @param Solarium_Query $query
      */
     public function __construct($options, $query)
@@ -81,7 +97,7 @@ abstract class Solarium_Client_Request
     }
 
     /**
-     * TODO
+     * Get HTTP request method
      *
      * @return string
      */
@@ -91,15 +107,21 @@ abstract class Solarium_Client_Request
     }
 
     /**
-     * TODO
+     * Get request uri
+     *
+     * To be implemented by query specific request builders.
      *
      * @abstract
-     * @return void
+     * @return string
      */
     abstract public function getUri();
 
     /**
-     * TODO
+     * Get raw POST data
+     *
+     * Returns null by default, disabling raw POST.
+     * If raw POST data is needed for a request the builder must override this
+     * method and return a data string. This string must be safely encoded.
      *
      * @return null
      */
@@ -109,7 +131,7 @@ abstract class Solarium_Client_Request
     }
 
     /**
-     * TODO
+     * Get request GET params
      *
      * @return array
      */
@@ -121,6 +143,12 @@ abstract class Solarium_Client_Request
     /**
      * Build a URL for this request
      *
+     * Based on {@link $_options} and {@link $_params} as input.
+     *
+     * {@internal} Solr expects multiple GET params of the same name instead of
+     * the PHP array type notation. Therefore the result of http_build_query
+     * has to be altered.
+     *
      * @return string
      */
     public function buildUri()
@@ -150,6 +178,8 @@ abstract class Solarium_Client_Request
     /**
      * Render a boolean attribute
      *
+     * For use in building XML messages
+     *
      * @param string $name
      * @param boolean $value
      * @return string
@@ -167,6 +197,8 @@ abstract class Solarium_Client_Request
     /**
      * Render an attribute
      *
+     * For use in building XML messages
+     *
      * @param string $name
      * @param striung $value
      * @return string
@@ -183,6 +215,9 @@ abstract class Solarium_Client_Request
     /**
      * Render a param with localParams
      *
+     * LocalParams can be use in various Solr GET params.
+     * {@link http://wiki.apache.org/solr/LocalParams}
+     *
      * @param string $value
      * @param array $localParams in key => value format
      * @return string with Solr localparams syntax
@@ -207,7 +242,20 @@ abstract class Solarium_Client_Request
         return $value;
     }
 
-
+    /**
+     * Add a param to the request
+     *
+     * This method makes adding params easy in two ways:
+     * - empty params are filtered out, so you don't to manually check each
+     * param
+     * - if you add the same param twice it will be converted into a multivalue
+     * param automatically. This way you don't need to check for single or
+     * multiple values beforehand.
+     *
+     * @param string $name
+     * @param string $value
+     * @return void
+     */
     public function addParam($name, $value)
     {
         if (0 === strlen($value)) return;

library/Solarium/Client/Request/Ping.php

@@ -36,16 +36,34 @@
  */
 
 /**
- * Builds ping request, for use in adapters.
+ * Build a ping request
+ *
+ * @package Solarium
+ * @subpackage Client
  */
 class Solarium_Client_Request_Ping extends Solarium_Client_Request
 {
 
+    /**
+     * Get uri
+     *
+     * Uses the default {@link buildUri()} method, no special uri needed in this
+     * case.
+     *
+     * @return string
+     */
     public function getUri()
     {
         return $this->buildUri();
     }
 
+    /**
+     * Get HTTP request method
+     *
+     * Ping has no useful result data, so a more optimal HEAD request is used.
+     *
+     * @return string
+     */
     public function getMethod()
     {
         return self::HEAD;

library/Solarium/Client/Request/Select.php

@@ -36,11 +36,22 @@
  */
 
 /**
- * Builds select request, for use in adapters.
+ * Build a select request
+ *
+ * @package Solarium
+ * @subpackage Client
  */
 class Solarium_Client_Request_Select extends Solarium_Client_Request
 {
 
+    /**
+     * Get uri
+     *
+     * Builds a complex uri based on the query settings
+     *
+     * @throws Solarium_Exception
+     * @return string
+     */
     public function getUri()
     {
         $this->_params = array(
@@ -94,6 +105,12 @@ class Solarium_Client_Request_Select extends Solarium_Client_Request
         return $this->buildUri();
     }
 
+    /**
+     * Add params for a field facet to request
+     *
+     * @param mixed $facet
+     * @return void
+     */
     public function addFacetField($facet)
     {
         $field = $facet->getField();
@@ -115,6 +132,12 @@ class Solarium_Client_Request_Select extends Solarium_Client_Request
         $this->addParam("f.$field.facet.method", $facet->getMethod());
     }
 
+    /**
+     * Add params for a field query to request
+     *
+     * @param mixed $facet
+     * @return void
+     */
     public function addFacetQuery($facet)
     {
         $this->addParam(

library/Solarium/Client/Request/Update.php

@@ -36,13 +36,18 @@
  */
 
 /**
- * Builds XML messages from update queries, for use in adapters.
+ * Build an update request
+ *
+ * @package Solarium
+ * @subpackage Client
  */
 class Solarium_Client_Request_Update extends Solarium_Client_Request
 {
 
     /**
-     * TODO
+     * Get HTTP request method
+     *
+     * Update uses raw POST data so a POST method has to be used.
      *
      * @return string
      */
@@ -52,7 +57,11 @@ class Solarium_Client_Request_Update extends Solarium_Client_Request
     }
 
     /**
-     * TODO
+     * Get uri
+     *
+     * Return the default url with the addition of the wt param.
+     * This enables a JSON response, that is the easiest and most efficient
+     * format to decode in the response handler.
      *
      * @return string
      */
@@ -63,7 +72,9 @@ class Solarium_Client_Request_Update extends Solarium_Client_Request
     }
 
     /**
-     * TODO
+     * Generates raw POST data
+     *
+     * Each commandtype is delegated to a separate builder method.
      *
      * @throws Solarium_Exception
      * @return string
@@ -99,6 +110,8 @@ class Solarium_Client_Request_Update extends Solarium_Client_Request
     }
 
     /**
+     * Build XML for an add command
+     *
      * @param Solarium_Query_Update_Command_Add $command
      * @return string
      */
@@ -130,6 +143,8 @@ class Solarium_Client_Request_Update extends Solarium_Client_Request
     }
 
     /**
+     * Build XML for a delete command
+     *
      * @param Solarium_Query_Update_Command_Delete $command
      * @return string
      */
@@ -150,6 +165,8 @@ class Solarium_Client_Request_Update extends Solarium_Client_Request
     }
 
     /**
+     * Build XML for an update command
+     *
      * @param Solarium_Query_Update_Command_Optimize $command
      * @return string
      */
@@ -165,6 +182,8 @@ class Solarium_Client_Request_Update extends Solarium_Client_Request
     }
 
     /**
+     * Build XML for a commit command
+     *
      * @param Solarium_Query_Update_Command_Commit $command
      * @return string
      */
@@ -183,6 +202,8 @@ class Solarium_Client_Request_Update extends Solarium_Client_Request
     }
 
     /**
+     * Build XMl for a rollback command
+     * 
      * @return string
      */
     public function buildRollbackXml()

library/Solarium/Client/Response.php

@@ -36,21 +36,63 @@
  */
 
 /**
- * Handles Solr response, for use in adapters.
+ * Base class for handling Solr HTTP responses
+ *
+ * Most {@link Solarium_Client_Adapter} implementations will use HTTP for
+ * communicating with Solr. While the HTTP part is adapter-specific, the parsing
+ * of the response into Solarium_Result classes is not. This abstract class is
+ * the base for several response handlers that do just that for the various
+ * querytypes.
+ *
+ * @package Solarium
+ * @subpackage Client
  */
 abstract class Solarium_Client_Response
 {
 
+    /**
+     * Query instance
+     *
+     * The query that was used for executing a request that led to this
+     * response. The query holds important settings for generating the right
+     * result, like the resultclass and documentclass settings.
+     *
+     * @var Solarium_Query
+     */
     protected $_query;
 
+    /**
+     * Response data
+     *
+     * A (json)decoded HTTP response body data array.
+     *
+     * @var array
+     */
     protected $_data;
 
+    /**
+     * Constructor
+     *
+     * @param Solarium_Query $query Query instance that was used for the request
+     * @param array $data Decoded data array of the HTTP response
+     */
     public function __construct($query, $data = null)
     {
         $this->_query = $query;
         $this->_data = $data;
     }
 
+    /**
+     * Get a Solarium_Result instance for the response
+     *
+     * When this method is called the actual response parsing is started.
+     *
+     * @internal Must be implemented in descendents because this parsing is
+     *  query specific.
+     *
+     * @abstract
+     * @return mixed
+     */
     abstract function getResult();
 
 }
\ No newline at end of file

library/Solarium/Client/Response/Select.php

@@ -36,14 +36,36 @@
  */
 
 /**
- * Handles Solr select response, for use in adapters.
+ * Parse select response data
+ *
+ * Will create a result object based on response data of the type
+ * {@Solarium_Result_Select} (or your own resultclass setting)
+ *
+ * @package Solarium
+ * @subpackage Client
  */
 class Solarium_Client_Response_Select extends Solarium_Client_Response
 {
+
+    /**
+     * Facet results
+     *
+     * Filled by the _addFacet* methods (for instance {@_addFacetField()})
+     *
+     * @var array
+     */
     protected $_facets = array();
 
+    /**
+     * Get a result instance for the response
+     *
+     * When this method is called the actual response parsing is done.
+     *
+     * @return mixed
+     */
     public function getResult()
     {
+        // create document instances
         $documentClass = $this->_query->getOption('documentclass');
         $documents = array();
         if (isset($this->_data['response']['docs'])) {
@@ -53,6 +75,7 @@ class Solarium_Client_Response_Select extends Solarium_Client_Response
             }
         }
 
+        // create facet results
         foreach ($this->_query->getFacets() AS $facet) {
             switch ($facet->getType()) {
                 case Solarium_Query_Select_Facet::FIELD:
@@ -66,16 +89,24 @@ class Solarium_Client_Response_Select extends Solarium_Client_Response
             }
         }
 
+        // add general data
         $status = $this->_data['responseHeader']['status'];
         $queryTime = $this->_data['responseHeader']['QTime'];
         $numFound = $this->_data['response']['numFound'];
 
+        // create the result instance that combines all data
         $resultClass = $this->_query->getOption('resultclass');
         return new $resultClass(
             $status, $queryTime, $numFound, $documents, $this->_facets
         );
     }
 
+    /**
+     * Add a facet result for a field facet
+     *
+     * @param mixed $facet
+     * @return void
+     */
     protected function _addFacetField($facet)
     {
         $key = $facet->getKey();
@@ -96,6 +127,12 @@ class Solarium_Client_Response_Select extends Solarium_Client_Response
         }
     }
 
+    /**
+     * Add a facet result for a field query
+     *
+     * @param mixed $facet
+     * @return void
+     */
     protected function _addFacetQuery($facet)
     {
         $key = $facet->getKey();

library/Solarium/Client/Response/Update.php

@@ -36,11 +36,24 @@
  */
 
 /**
- * Handles Solr select response, for use in adapters.
+ * Parse update response data
+ *
+ * Will create a result object based on response data of the type
+ * {@Solarium_Result_Update} (or your own resultclass setting)
+ *
+ * @package Solarium
+ * @subpackage Client
  */
 class Solarium_Client_Response_Update extends Solarium_Client_Response
 {
 
+    /**
+     * Get a result instance for the response
+     *
+     * When this method is called the actual response parsing is done.
+     *
+     * @return mixed
+     */
     public function getResult()
     {
         $resultClass = $this->_query->getOption('resultclass');

tests/Solarium/Client/Request/SelectTest.php

@@ -46,6 +46,15 @@ class Solarium_Client_Request_SelectTest extends PHPUnit_Framework_TestCase
         $this->_query = new Solarium_Query_Select;
     }
 
+    public function testGetMethod()
+    {
+        $request = new Solarium_Client_Request_Select($this->_options, $this->_query);
+        $this->assertEquals(
+            Solarium_Client_Request::GET,
+            $request->getMethod()
+        );
+    }
+
     public function testSelectUrlWithDefaultValues()
     {
         $request = new Solarium_Client_Request_Select($this->_options, $this->_query);