- many phpdoc improvements

library/Solarium/Client.php

@@ -86,7 +86,7 @@ class Solarium_Client extends Solarium_Configurable
     protected $_adapter;
 
     /**
-     * {@inheritdoc}
+     * Initialization hook
      *
      * In this case the path needs to be cleaned of trailing slashes.
      * @see setPath()
@@ -103,11 +103,15 @@ class Solarium_Client extends Solarium_Configurable
     }
 
     /**
-     * {@inheritdoc}
+     * Set an option
      *
      * If any option of this client is changed after the adapter has been
      * instantiated the change is propagated to the adapter. This allows for
      * switching the client to another core for a second query, for instance.
+     *
+     * @param string $name
+     * @param mixed $value
+     * @return Solarium_Configurable
      */
     protected function _setOption($name, $value)
     {

library/Solarium/Client/Adapter/ZendHttp.php

@@ -44,6 +44,9 @@
  *
  * To use this adapter you need to have the Zend Framework in your include path,
  * autoloader or manually included.
+ *
+ * @package Solarium
+ * @subpackage Client
  */
 class Solarium_Client_Adapter_ZendHttp extends Solarium_Client_Adapter_Http
 {

library/Solarium/Query/Ping.php

@@ -37,6 +37,13 @@
 
 /**
  * Ping query
+ *
+ * Use a ping query to test Solr communication.
+ * A ping query has only two options, the path to use and the resultclass. See
+ * {@link Solarium_Query} for the methods to set these options.
+ *
+ * @package Solarium
+ * @subpackage Query
  */
 class Solarium_Query_Ping extends Solarium_Query
 {

library/Solarium/Query/Select.php

@@ -37,6 +37,9 @@
 
 /**
  * Select Query
+ *
+ * @package Solarium
+ * @subpackage Query
  */
 class Solarium_Query_Select extends Solarium_Query
 {
@@ -93,12 +96,13 @@ class Solarium_Query_Select extends Solarium_Query
     /**
      * Initialize options
      *
+     * Several options need some extra checks or setup work, for these options
+     * the setters are called.
+     * 
      * @return void
      */
     protected function _init()
     {
-        // several options need some extra checks or setup work, call the
-        // setters for these
         foreach ($this->_options AS $name => $value) {
             switch ($name) {
                 case 'query':
@@ -127,7 +131,10 @@ class Solarium_Query_Select extends Solarium_Query
     }
 
     /**
-     * Set the query string (overwrites the current value)
+     * Set the query string
+     *
+     * Overwrites the current value. You are responsible for the correct
+     * escaping of user input.
      *
      * @param string $query
      * @return Solarium_Query Provides fluent interface
@@ -180,7 +187,9 @@ class Solarium_Query_Select extends Solarium_Query
     }
 
     /**
-     * Get the current resultclass option (classname)
+     * Get the current resultclass option
+     *
+     * The value is a classname, not an instance
      *
      * @return string
      */
@@ -201,7 +210,9 @@ class Solarium_Query_Select extends Solarium_Query
     }
 
     /**
-     * Get the current documentclass option (classname)
+     * Get the current documentclass option
+     *
+     * The value is a classname, not an instance
      * 
      * @return string
      */
@@ -302,7 +313,9 @@ class Solarium_Query_Select extends Solarium_Query
     }
 
     /**
-     * Set multiple fields at once, overwriting any existing fields.
+     * Set multiple fields
+     *
+     * This overwrites any existing fields
      *
      * @param array $fields
      * @return Solarium_Query Provides fluent interface
@@ -330,7 +343,8 @@ class Solarium_Query_Select extends Solarium_Query
     }
 
     /**
-     * Add multiple sort fields.
+     * Add multiple sort fields
+     *
      * The input array must contain fieldnames as keys and the order as values.
      *
      * @param array $sortFields
@@ -373,6 +387,8 @@ class Solarium_Query_Select extends Solarium_Query
 
     /**
      * Get a list of the sortfields
+     *
+     * @return array
      */
     public function getSortFields()
     {
@@ -380,7 +396,9 @@ class Solarium_Query_Select extends Solarium_Query
     }
 
     /**
-     * Set multiple sortfields at once, overwriting any existing sortfields.
+     * Set multiple sortfields
+     *
+     * This overwrites any existing sortfields
      *
      * @param array $fields
      * @return Solarium_Query Provides fluent interface
@@ -396,6 +414,9 @@ class Solarium_Query_Select extends Solarium_Query
     /**
      * Add a filter query
      *
+     * Supports a filterquery instance or a config array, in that case a new
+     * filterquery instance wil be created based on the options.
+     *
      * @param Solarium_Query_Select_FilterQuery|array $filterQuery
      * @return Solarium_Query Provides fluent interface
      */
@@ -487,7 +508,9 @@ class Solarium_Query_Select extends Solarium_Query
     }
 
     /**
-     * Set multiple filterqueries at once, overwriting any existing queries
+     * Set multiple filterqueries
+     *
+     * This overwrites any existing filterqueries
      *
      * @param array $filterQueries
      */
@@ -592,7 +615,9 @@ class Solarium_Query_Select extends Solarium_Query
     }
 
     /**
-     * Set multiple facets at once, overwriting any existing facets
+     * Set multiple facets
+     *
+     * This overwrites any existing facets
      *
      * @param array $facets
      */

library/Solarium/Query/Select/Facet.php

@@ -36,7 +36,12 @@
  */
 
 /**
- * Facet query
+ * Facet base class
+ *
+ * @link http://wiki.apache.org/solr/SimpleFacetParameters
+ *
+ * @package Solarium
+ * @subpackage Query
  */
 abstract class Solarium_Query_Select_Facet extends Solarium_Configurable
 {
@@ -163,7 +168,9 @@ abstract class Solarium_Query_Select_Facet extends Solarium_Configurable
     }
 
     /**
-     * Set multiple excludes at once, overwriting any existing excludes
+     * Set multiple excludes
+     *
+     * This overwrites any existing excludes
      *
      * @param array $excludes
      */

library/Solarium/Query/Select/Facet/Field.php

@@ -37,6 +37,11 @@
 
 /**
  * Facet query
+ *
+ * @link http://wiki.apache.org/solr/SimpleFacetParameters#Field_Value_Faceting_Parameters
+ *
+ * @package Solarium
+ * @subpackage Query
  */
 class Solarium_Query_Select_Facet_Field extends Solarium_Query_Select_Facet
 {
@@ -63,6 +68,8 @@ class Solarium_Query_Select_Facet_Field extends Solarium_Query_Select_Facet
     );
 
     /**
+     * Get the facet type
+     * 
      * @return string
      */
     public function getType()
@@ -92,7 +99,9 @@ class Solarium_Query_Select_Facet_Field extends Solarium_Query_Select_Facet
     }
 
     /**
-     * Set the facet sort order (use one of the constants)
+     * Set the facet sort order
+     *
+     * Use one of the SORT_* constants as the value
      *
      * @param string $sort
      * @return Solarium_Query_Select_Facet_Field Provides fluent interface
@@ -218,7 +227,9 @@ class Solarium_Query_Select_Facet_Field extends Solarium_Query_Select_Facet
     }
 
     /**
-     * Set the facet method (use one of the constants as value)
+     * Set the facet method
+     *
+     * Use one of the METHOD_* constants as value
      *
      * @param string $method
      * @return Solarium_Query_Select_Facet_Field Provides fluent interface

library/Solarium/Query/Select/Facet/Query.php

@@ -37,6 +37,11 @@
 
 /**
  * Facet query
+ *
+ * @link http://wiki.apache.org/solr/SimpleFacetParameters#facet.query_:_Arbitrary_Query_Faceting
+ *
+ * @package Solarium
+ * @subpackage Query
  */
 class Solarium_Query_Select_Facet_Query extends Solarium_Query_Select_Facet
 {
@@ -51,6 +56,8 @@ class Solarium_Query_Select_Facet_Query extends Solarium_Query_Select_Facet
     );
 
     /**
+     * Get the facet type
+     * 
      * @return string
      */
     public function getType()
@@ -59,7 +66,9 @@ class Solarium_Query_Select_Facet_Query extends Solarium_Query_Select_Facet
     }
 
     /**
-     * Set the query string (overwrites the current value)
+     * Set the query string
+     *
+     * This overwrites the current value
      *
      * @param string $query
      * @return Solarium_Query_Select_Facet_Query Provides fluent interface

library/Solarium/Query/Select/FilterQuery.php

@@ -37,6 +37,11 @@
 
 /**
  * Filterquery
+ *
+ * @link http://wiki.apache.org/solr/CommonQueryParameters#fq
+ *
+ * @package Solarium
+ * @subpackage Query
  */
 class Solarium_Query_Select_FilterQuery extends Solarium_Configurable
 {
@@ -96,7 +101,9 @@ class Solarium_Query_Select_FilterQuery extends Solarium_Configurable
     }
 
     /**
-     * Set the query string (overwrites the current value)
+     * Set the query string
+     *
+     * This overwrites the current value
      *
      * @param string $query
      * @return Solarium_Query Provides fluent interface
@@ -180,7 +187,9 @@ class Solarium_Query_Select_FilterQuery extends Solarium_Configurable
     }
 
     /**
-     * Set multiple tags at once, overwriting any existing tags
+     * Set multiple tags
+     *
+     * This overwrites any existing tags
      *
      * @param array $filterQueries
      * @return Solarium_Query_Select_FilterQuery Provides fluent interface
@@ -191,6 +200,4 @@ class Solarium_Query_Select_FilterQuery extends Solarium_Configurable
         return $this->addTags($filterQueries);
     }
 
-
-
 }
\ No newline at end of file

library/Solarium/Query/Update.php

@@ -36,7 +36,14 @@
  */
 
 /**
- * Update Query
+ * Update query
+ *
+ * Can be used to send multiple update commands to solr, e.g. add, delete,
+ * rollback, commit, optimize.
+ * Multiple commands of any type can be combined into a single update query.
+ *
+ * @package Solarium
+ * @subpackage Query
  */
 class Solarium_Query_Update extends Solarium_Query
 {
@@ -54,7 +61,10 @@ class Solarium_Query_Update extends Solarium_Query
     );
 
     /**
-     * Array of commands that define this update query
+     * Array of commands
+     *
+     * The commands will be executed in the order of this array, this can be
+     * important in some cases. For instance a rollback.
      *
      * @var array
      */
@@ -71,8 +81,10 @@ class Solarium_Query_Update extends Solarium_Query
     }
 
     /**
-     * Add a command to this update query. This must be an instance of one of
-     * the Solarium_Query_Update_* classes.
+     * Add a command to this update query
+     *
+     * The command must be an instance of one of the Solarium_Query_Update_*
+     * classes.
      *
      * @param string $key
      * @param object $command
@@ -90,7 +102,7 @@ class Solarium_Query_Update extends Solarium_Query
     }
 
     /**
-     * Remove a command, by key
+     * Remove a command by key
      *
      * @param string $key
      * @return Solarium_Query_Update Provides fluent interface
@@ -104,9 +116,10 @@ class Solarium_Query_Update extends Solarium_Query
     }
 
     /**
-     * Convenience method for adding a rollback.
+     * Convenience method for adding a rollback command
+     *
      * If you need more control, like choosing a key for the command you need to
-     * create you own command instances and you the add method.
+     * create you own command instance and use the add method.
      *
      * @return Solarium_Query_Update Provides fluent interface
      */
@@ -116,9 +129,10 @@ class Solarium_Query_Update extends Solarium_Query
     }
 
     /**
-     * Convenience method for adding a delete query.
+     * Convenience method for adding a delete query command
+     *
      * If you need more control, like choosing a key for the command you need to
-     * create you own command instances and you the add method.
+     * create you own command instance and use the add method.
      *
      * @param string $query
      * @return Solarium_Query_Update Provides fluent interface
@@ -132,9 +146,10 @@ class Solarium_Query_Update extends Solarium_Query
     }
 
     /**
-     * Convenience method to add multiple delete queries to the update
+     * Convenience method to add a multi delete query command
+     *
      * If you need more control, like choosing a key for the command you need to
-     * create you own command instances and you the add method.
+     * create you own command instance and use the add method.
      *
      * @param string $key
      * @param array $queries
@@ -149,9 +164,10 @@ class Solarium_Query_Update extends Solarium_Query
     }
 
     /**
-     * Convenience method to add a delete by ID to the update
+     * Convenience method to add a delete by ID command
+     *
      * If you need more control, like choosing a key for the command you need to
-     * create you own command instances and you the add method.
+     * create you own command instance and use the add method.
      *
      * @param int|string $id
      * @return Solarium_Query_Update Provides fluent interface
@@ -165,9 +181,10 @@ class Solarium_Query_Update extends Solarium_Query
     }
 
     /**
-     * Convenience method to add delete by multiple IDs to the update
+     * Convenience method to add a delete by IDs command
+     *
      * If you need more control, like choosing a key for the command you need to
-     * create you own command instances and you the add method.
+     * create you own command instance and use the add method.
      *
      * @param array $id
      * @return Solarium_Query_Update Provides fluent interface
@@ -181,9 +198,10 @@ class Solarium_Query_Update extends Solarium_Query
     }
 
     /**
-     * Convenience method to add a document to the update.
+     * Convenience method to add a 'add document' command
+     *
      * If you need more control, like choosing a key for the command you need to
-     * create you own command instances and you the add method.
+     * create you own command instance and use the add method.
      *
      * @param Solarium_Document_ReadWrite $document
      * @param boolean $overwrite
@@ -197,9 +215,10 @@ class Solarium_Query_Update extends Solarium_Query
     }
 
     /**
-     * Convenience method to add multiple documents to the update.
+     * Convenience method to add a 'add documents' command
+     *
      * If you need more control, like choosing a key for the command you need to
-     * create you own command instances and you the add method.
+     * create you own command instance and use the add method.
      *
      * @param array $documents
      * @param boolean $overwrite
@@ -218,9 +237,10 @@ class Solarium_Query_Update extends Solarium_Query
     }
 
     /**
-     * Convenience method to add a commit command to the update
+     * Convenience method to add a commit command
+     *
      * If you need more control, like choosing a key for the command you need to
-     * create you own command instances and you the add method.
+     * create you own command instance and use the add method.
      *
      * @param boolean $waitFlush
      * @param boolean $waitSearcher
@@ -240,9 +260,10 @@ class Solarium_Query_Update extends Solarium_Query
     }
 
     /**
-     * Convenience method to add an optimize command to the update
+     * Convenience method to add an optimize command
+     *
      * If you need more control, like choosing a key for the command you need to
-     * create you own command instances and you the add method.
+     * create you own command instance and use the add method.
      *
      * @param boolean $waitFlush
      * @param boolean $waitSearcher

library/Solarium/Query/Update/Command.php

@@ -36,7 +36,10 @@
  */
 
 /**
- * Update query add (documents) command
+ * Update query command base class
+ *
+ * @package Solarium
+ * @subpackage Query
  */
 abstract class Solarium_Query_Update_Command extends Solarium_Configurable
 {

library/Solarium/Query/Update/Command/Add.php

@@ -36,7 +36,13 @@
  */
 
 /**
- * Update query add (documents) command
+ * Update query add command
+ *
+ * For details about the Solr options see:
+ * @link http://wiki.apache.org/solr/UpdateXmlMessages#add.2BAC8-update
+ *
+ * @package Solarium
+ * @subpackage Query
  */
 class Solarium_Query_Update_Command_Add extends Solarium_Query_Update_Command
 {
@@ -48,6 +54,11 @@ class Solarium_Query_Update_Command_Add extends Solarium_Query_Update_Command
      */
     protected $_documents = array();
 
+    /**
+     * Get command type
+     * 
+     * @return string
+     */
     public function getType()
     {
         return Solarium_Query_Update_Command::ADD;
@@ -79,12 +90,19 @@ class Solarium_Query_Update_Command_Add extends Solarium_Query_Update_Command
         return $this;
     }
 
+    /**
+     * Get all documents
+     * 
+     * @return array
+     */
     public function getDocuments()
     {
         return $this->_documents;
     }
 
     /**
+     * Set overwrite option
+     *
      * @param boolean $overwrite
      * @return Solarium_Query_Update_Add Provides fluent interface
      */
@@ -94,6 +112,8 @@ class Solarium_Query_Update_Command_Add extends Solarium_Query_Update_Command
     }
 
     /**
+     * Get overwrite option
+     *
      * @return boolean
      */
     public function getOverwrite()
@@ -102,6 +122,8 @@ class Solarium_Query_Update_Command_Add extends Solarium_Query_Update_Command
     }
 
     /**
+     * Get commitWithin option
+     *
      * @param boolean $commitWithin
      * @return Solarium_Query_Update_Add Provides fluent interface
      */
@@ -111,6 +133,8 @@ class Solarium_Query_Update_Command_Add extends Solarium_Query_Update_Command
     }
 
     /**
+     * Set commitWithin option
+     * 
      * @return boolean
      */
     public function getCommitWithin()

library/Solarium/Query/Update/Command/Commit.php

@@ -37,16 +37,29 @@
 
 /**
  * Update query commit command
+ *
+ * For details about the Solr options see:
+ * @link http://wiki.apache.org/solr/UpdateXmlMessages#A.22commit.22_and_.22optimize.22
+ *
+ * @package Solarium
+ * @subpackage Query
  */
 class Solarium_Query_Update_Command_Commit extends Solarium_Query_Update_Command
 {
 
+    /**
+     * Get command type
+     * 
+     * @return string
+     */
     public function getType()
     {
         return Solarium_Query_Update_Command::COMMIT;
     }
 
     /**
+     * Get waitFlush option
+     * 
      * @return boolean
      */
     public function getWaitFlush()
@@ -55,6 +68,8 @@ class Solarium_Query_Update_Command_Commit extends Solarium_Query_Update_Command
     }
 
     /**
+     * Set waitFlush option
+     * 
      * @param boolean $waitFlush
      * @return Solarium_Query_Update_Commit Provides fluent interface
      */
@@ -64,6 +79,8 @@ class Solarium_Query_Update_Command_Commit extends Solarium_Query_Update_Command
     }
 
     /**
+     * Get waitSearcher option
+     *
      * @return boolean
      */
     public function getWaitSearcher()
@@ -72,6 +89,8 @@ class Solarium_Query_Update_Command_Commit extends Solarium_Query_Update_Command
     }
 
     /**
+     * Set waitSearcher option
+     * 
      * @param boolean $waitSearcher
      * @return Solarium_Query_Update_Commit Provides fluent interface
      */
@@ -81,6 +100,8 @@ class Solarium_Query_Update_Command_Commit extends Solarium_Query_Update_Command
     }
 
     /**
+     * Get expungeDeletes option
+     *
      * @return boolean
      */
     public function getExpungeDeletes()
@@ -89,6 +110,8 @@ class Solarium_Query_Update_Command_Commit extends Solarium_Query_Update_Command
     }
 
     /**
+     * Set expungeDeletes option
+     * 
      * @param boolean $expungeDeletes
      * @return Solarium_Query_Update_Commit Provides fluent interface
      */

library/Solarium/Query/Update/Command/Delete.php

@@ -37,6 +37,12 @@
 
 /**
  * Update query delete command
+ *
+ * For details about the Solr options see:
+ * @link http://wiki.apache.org/solr/UpdateXmlMessages#A.22delete.22_by_ID_and_by_Query
+ *
+ * @package Solarium
+ * @subpackage Query
  */
 class Solarium_Query_Update_Command_Delete extends Solarium_Query_Update_Command
 {
@@ -55,6 +61,11 @@ class Solarium_Query_Update_Command_Delete extends Solarium_Query_Update_Command
      */
     protected $_queries = array();
 
+    /**
+     * Get command type
+     * 
+     * @return string
+     */
     public function getType()
     {
         return Solarium_Query_Update_Command::DELETE;
@@ -62,6 +73,7 @@ class Solarium_Query_Update_Command_Delete extends Solarium_Query_Update_Command
 
     /**
      * Build ids/queries based on options
+     * 
      * @return void
      */
     protected function _init()

library/Solarium/Query/Update/Command/Optimize.php

@@ -37,17 +37,29 @@
 
 /**
  * Update query optimize command
+ *
+ * For details about the Solr options see:
+ * @link http://wiki.apache.org/solr/UpdateXmlMessages#A.22commit.22_and_.22optimize.22
+ *
+ * @package Solarium
+ * @subpackage Query
  */
 class Solarium_Query_Update_Command_Optimize
     extends Solarium_Query_Update_Command
 {
-
+    /**
+     * Get command type
+     * 
+     * @return string
+     */
     public function getType()
     {
         return Solarium_Query_Update_Command::OPTIMIZE;
     }
 
     /**
+     * Get waitFlush option
+     *
      * @return boolean
      */
     public function getWaitFlush()
@@ -56,6 +68,8 @@ class Solarium_Query_Update_Command_Optimize
     }
 
     /**
+     * Set waitFlush option
+     *
      * @param boolean $waitFlush
      * @return Solarium_Query_Update_Optimize Provides fluent interface
      */
@@ -65,6 +79,8 @@ class Solarium_Query_Update_Command_Optimize
     }
 
     /**
+     * Get waitSearcher option
+     *
      * @return boolean
      */
     public function getWaitSearcher()
@@ -73,6 +89,8 @@ class Solarium_Query_Update_Command_Optimize
     }
 
     /**
+     * Set waitSearcher option
+     *
      * @param boolean $waitSearcher
      * @return Solarium_Query_Update_Optimize Provides fluent interface
      */
@@ -82,6 +100,8 @@ class Solarium_Query_Update_Command_Optimize
     }
 
     /**
+     * Get maxSegments option
+     *
      * @return boolean
      */
     public function getMaxSegments()
@@ -90,6 +110,8 @@ class Solarium_Query_Update_Command_Optimize
     }
 
     /**
+     * Set maxSegments option
+     * 
      * @param boolean $maxSegments
      * @return Solarium_Query_Update_Optimize Provides fluent interface
      */

library/Solarium/Query/Update/Command/Rollback.php

@@ -37,10 +37,21 @@
 
 /**
  * Update query rollback command
+ *
+ * For details see:
+ * @link http://wiki.apache.org/solr/UpdateXmlMessages#A.22rollback.22
+ *
+ * @package Solarium
+ * @subpackage Query
  */
 class Solarium_Query_Update_Command_Rollback
     extends Solarium_Query_Update_Command
 {
+    /**
+     * Get command type
+     *
+     * @return string
+     */
     public function getType()
     {
         return Solarium_Query_Update_Command::ROLLBACK;