- many phpdoc improvements

library/Solarium/Document/ReadOnly.php

@@ -36,7 +36,13 @@
  */
 
 /**
- * Solr query result read-only document
+ * Read-only Solr document
+ *
+ * This is the default Solr document type returned by a select query. You can
+ * access the fields as object properties or iterate over all fields.
+ *
+ * @package Solarium
+ * @subpackage Document
  */
 class Solarium_Document_ReadOnly implements IteratorAggregate, Countable
 {
@@ -50,7 +56,7 @@ class Solarium_Document_ReadOnly implements IteratorAggregate, Countable
 
 
     /**
-     * Constructor.
+     * Constructor
      *
      * @param array $fields
      */
@@ -61,7 +67,7 @@ class Solarium_Document_ReadOnly implements IteratorAggregate, Countable
 
 
     /**
-     * Return the complete array of fields
+     * Get all fields
      *
      * @return array
      */
@@ -70,8 +76,9 @@ class Solarium_Document_ReadOnly implements IteratorAggregate, Countable
         return $this->_fields;
     }
 
-
     /**
+     * Get field value by name
+     *
      * Magic access method for accessing fields as properties of this document
      * object, by field name.
      *
@@ -86,9 +93,10 @@ class Solarium_Document_ReadOnly implements IteratorAggregate, Countable
 
         return $this->_fields[$name];
     }
-
     
     /**
+     * Set field value
+     *
      * Magic method for setting a field as property of this object. Since this
      * is a readonly document an exception will be thrown to prevent this.
      *

library/Solarium/Document/ReadWrite.php

@@ -36,7 +36,20 @@
  */
 
 /**
- * Updateable Solr document
+ * Read/Write Solr document
+ *
+ * This document type is used for update queries. It has all of the features of
+ * the readonly document and it also allows for updating or adding fields and
+ * boosts.
+ *
+ * While it is possible to use this document type for a select, alter it and use
+ * it in an update query (effectively the 'edit' that Solr doesn't have) this
+ * is not recommended. Most Solr indexes have fields that are indexed and not
+ * stored. You will loose that data because it is impossible to retrieve it from
+ * Solr. Always update from the original data source.
+ *
+ * @package Solarium
+ * @subpackage Document
  */
 class Solarium_Document_ReadWrite extends Solarium_Document_ReadOnly
 {
@@ -50,6 +63,8 @@ class Solarium_Document_ReadWrite extends Solarium_Document_ReadOnly
 
     /**
      * Field boosts
+     *
+     * Using fieldname as the key and the boost as the value
      * 
      * @var array
      */
@@ -67,7 +82,9 @@ class Solarium_Document_ReadWrite extends Solarium_Document_ReadOnly
     }
 
     /**
-     * Add a field value. If a field already has a value it will be converted
+     * Add a field value
+     *
+     * If a field already has a value it will be converted
      * to a multivalue field.
      *
      * @param string $key
@@ -93,7 +110,9 @@ class Solarium_Document_ReadWrite extends Solarium_Document_ReadOnly
     }
 
     /**
-     * Set a field value. If a field already has a value it will be overwritten.
+     * Set a field value
+     *
+     * If a field already has a value it will be overwritten.
      *
      * @param string $key
      * @param mixed $value
@@ -109,7 +128,7 @@ class Solarium_Document_ReadWrite extends Solarium_Document_ReadOnly
     }
 
     /**
-     * Remove a field from this document
+     * Remove a field
      *
      * @param string $key
      * @return Solarium_Document_ReadWrite Provides fluent interface
@@ -128,7 +147,7 @@ class Solarium_Document_ReadWrite extends Solarium_Document_ReadOnly
     }
 
     /**
-     * Get the boost value for a single document field
+     * Get the boost value for a field
      *
      * @param string $key
      * @return float
@@ -143,7 +162,7 @@ class Solarium_Document_ReadWrite extends Solarium_Document_ReadOnly
     }
 
     /**
-     * Set the boost value for a single field
+     * Set the boost value for a field
      *
      * @param string $key
      * @param float $boost
@@ -156,7 +175,7 @@ class Solarium_Document_ReadWrite extends Solarium_Document_ReadOnly
     }
 
     /**
-     * Set the boost value for this document
+     * Set the document boost value
      *
      * @param float $boost
      * @return Solarium_Document_ReadWrite Provides fluent interface
@@ -168,7 +187,7 @@ class Solarium_Document_ReadWrite extends Solarium_Document_ReadOnly
     }
 
     /**
-     * Get the boost value for this document
+     * Get the document boost value
      *
      * @return float
      */
@@ -178,6 +197,8 @@ class Solarium_Document_ReadWrite extends Solarium_Document_ReadOnly
     }
 
     /**
+     * Set field value
+     *
      * Magic method for setting fields as properties of this document
      * object, by field name.
      *

library/Solarium/Result/Query.php

@@ -38,6 +38,9 @@
 /**
  * Query result
  *
+ * This base class provides methods for two common result values: status and
+ * querytime.
+ *
  * @package Solarium
  * @subpackage Result
  */
@@ -45,16 +48,25 @@ class Solarium_Result_Query
 {
 
     /**
+     * Status code returned by Solr
+     *
      * @var int
      */
     protected $_status;
     
     /**
+     * Solr index queryTime
+     *
+     * This doesn't include things like the HTTP responsetime. Purely the Solr
+     * query execution time.
+     *
      * @var int
      */
     protected $_queryTime;
 
     /**
+     * Constructor
+     *
      * @param int $status
      * @param int $queryTime
      * @return void
@@ -66,6 +78,8 @@ class Solarium_Result_Query
     }
 
     /**
+     * Get Solr status code
+     *
      * @return int
      */
     public function getStatus()
@@ -74,6 +88,11 @@ class Solarium_Result_Query
     }
 
     /**
+     * Get Solr query time
+     *
+     * This doesn't include things like the HTTP responsetime. Purely the Solr
+     * query execution time.
+     * 
      * @return int
      */
     public function getQueryTime()

library/Solarium/Result/Select.php

@@ -37,14 +37,35 @@
 
 /**
  * Select query result
+ *
+ * This is the standard resulttype for a select query. Example usage:
+ * <code>
+ * // total solr results
+ * $result->getNumFound();
+ *
+ * // results fetched
+ * count($result);
+ *
+ * // get a single facet by key
+ * $result->getFacet('category');
+ *
+ * // iterate over fetched docs
+ * foreach ($result AS $doc) {
+ *    ....
+ * }
+ * </code>
+ *
+ * @package Solarium
+ * @subpackage Result
  */
 class Solarium_Result_Select extends Solarium_Result_Query
     implements IteratorAggregate, Countable
 {
 
     /**
-     * Number of documents found by Solr (this is NOT the number of document
-     * fetched from Solr!)
+     * Solr numFound
+     *
+     * This is NOT the number of document fetched from Solr!
      *
      * @var int
      */
@@ -65,15 +86,10 @@ class Solarium_Result_Select extends Solarium_Result_Query
     protected $_facets;
 
     /**
-     * Pointer to document array position for iterator implementation
+     * Constructor
      *
-     * @var int
-     */
-    protected $_position;
-
-    /**
-     * Constructor. This is the only point where data can be set in this
-     * immutable value object.
+     * This is the only point where data can be set in this immutable value
+     * object.
      *
      * @param int $status
      * @param int $queryTime
@@ -93,6 +109,8 @@ class Solarium_Result_Select extends Solarium_Result_Query
     }
 
     /**
+     * get Solr numFound
+     *
      * Returns the total number of documents found by Solr (this is NOT the
      * number of document fetched from Solr!)
      *
@@ -104,7 +122,7 @@ class Solarium_Result_Select extends Solarium_Result_Query
     }
 
     /**
-     * Return all fetched documents in an array
+     * Get all documents
      *
      * @return array
      */
@@ -114,7 +132,7 @@ class Solarium_Result_Select extends Solarium_Result_Query
     }
 
     /**
-     * Return all facet results in an array
+     * Get all facet results
      *
      * @return array
      */
@@ -124,7 +142,7 @@ class Solarium_Result_Select extends Solarium_Result_Query
     }
 
     /**
-     * Return a facet result
+     * Get a facet result by key
      *
      * @param string $key
      * @return Solarium_Result_Select_Facet

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

@@ -36,7 +36,14 @@
  */
 
 /**
- * Select query facet result
+ * Select field facet result
+ *
+ * A field facet will usually return a dataset of multiple rows, in each row a
+ * value and it's count. You can access the values as an array using
+ * {@link getValues()} or iterate this object.
+ *
+ * @package Solarium
+ * @subpackage Result
  */
 class Solarium_Result_Select_Facet_Field implements IteratorAggregate, Countable
 {

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

@@ -37,12 +37,18 @@
 
 /**
  * Select query facet result
+ *
+ * Since a query facet has only a single result, the count for the query, this
+ * is a very simple object.
+ *
+ * @package Solarium
+ * @subpackage Result
  */
 class Solarium_Result_Select_Facet_Query
 {
 
     /**
-     * Value
+     * Value (count)
      *
      * @var mixed
      */

library/Solarium/Result/Update.php

@@ -38,6 +38,12 @@
 /**
  * Update result
  *
+ * An update query only returns a query time and status. Both are accessible
+ * using the methods provided by {@link Solarium_Result_Query}.
+ *
+ * @internal For now this class only exists to distinguish the different result
+ *  types. It might get some extra behaviour in the future.
+ *
  * @package Solarium
  * @subpackage Result
  */