Refs #4200, tweaked RankingQuery docs.

1 files changed, 54 insertions, 44 deletions

diff --git a/core/RankingQuery.php b/core/RankingQuery.php
index e72d76f193..70977f7d01 100644
--- a/core/RankingQuery.php
+++ b/core/RankingQuery.php
@@ -21,26 +21,26 @@ use Exception;
  *
  * The general use case looks like this:
  *
- * // limit to 500 rows + "Others"
- * $rankingQuery = new RankingQuery(500);
+ *     // limit to 500 rows + "Others"
+ *     $rankingQuery = new RankingQuery();
+ *     $rankingQuery->setLimit(500);
  *
- * // idaction_url will be "Others" in the row that contains the aggregated rest
- * $rankingQuery->addLabelColumn('idaction_url');
+ *     // idaction_url will be "Others" in the row that contains the aggregated rest
+ *     $rankingQuery->addLabelColumn('idaction_url');
  *
- * // the actual query. it's important to sort it before the limit is applied
- * $sql = 'SELECT idaction_url, COUNT(*) AS nb_hits
- *         FROM log_link_visit_action
- *         GROUP BY idaction_url
- *         ORDER BY nb_hits DESC';
- *
- * // execute the query
- * $rankingQuery->execute($sql);
+ *     // the actual query. it's important to sort it before the limit is applied
+ *     $sql = 'SELECT idaction_url, COUNT(*) AS nb_hits
+ *             FROM log_link_visit_action
+ *             GROUP BY idaction_url
+ *             ORDER BY nb_hits DESC';
  *
+ *     // execute the query
+ *     $rankingQuery->execute($sql);
  *
  * For more examples, see RankingQueryTest.php
  *
- *
  * @package Piwik
+ * @api
  */
 class RankingQuery
 {
@@ -90,8 +90,9 @@ class RankingQuery
     private $othersLabelValue = 'Others';
 
     /**
-     * The constructor.
-     * Can be used as a shortcut for setLimit()
+     * Constructor.
+     * 
+     * @param int|false $limit The result row limit. See [setLimit](#setLimit).
      */
     public function __construct($limit = false)
     {
@@ -101,9 +102,9 @@ class RankingQuery
     }
 
     /**
-     * Set the limit after which everything is grouped to "Others"
+     * Set the limit after which everything is grouped to "Others".
      *
-     * @param $limit int
+     * @param int $limit
      */
     public function setLimit($limit)
     {
@@ -113,7 +114,7 @@ class RankingQuery
     /**
      * Set the value to use for the label in the 'Others' row.
      *
-     * @param $value string
+     * @param string $value
      */
     public function setOthersLabel($value)
     {
@@ -124,7 +125,7 @@ class RankingQuery
      * Add a label column.
      * Labels are the columns that are replaced with "Others" after the limit.
      *
-     * @param $labelColumn string|array
+     * @param string|array $labelColumn
      */
     public function addLabelColumn($labelColumn)
     {
@@ -141,8 +142,8 @@ class RankingQuery
      * Add a column that has be added to the outer queries.
      *
      * @param $column
-     * @param string|bool $aggregationFunction string
-     *         If set, this function is used to aggregate the values of "Others"
+     * @param string|bool $aggregationFunction If set, this function is used to aggregate the values of "Others",
+     *                                         eg, `'min'`, `'max'` or `'sum'`.
      */
     public function addColumn($column, $aggregationFunction = false)
     {
@@ -156,13 +157,13 @@ class RankingQuery
     }
 
     /**
-     * The inner query can have a column that marks the rows that shall be excluded from limiting.
-     * If the column contains 0, rows are handled as usual. For values greater than 0, separate
-     * groups are made. If this method is used, generate() returns both the regular result and
-     * the excluded columns separately.
+     * Sets a column that will be used to filter the result into two categories.
+     * Rows where this column has a value > 0 will be removed from the result and put
+     * into another array. Both the result and the array of excluded rows are returned
+     * by [execute](#execute).
      *
-     * @param $column string  name of the column
-     * @throws Exception when method is used more than once
+     * @param $column string Name of the column.
+     * @throws Exception if method is used more than once.
      */
     public function setColumnToMarkExcludedRows($column)
     {
@@ -175,16 +176,21 @@ class RankingQuery
     }
 
     /**
-     * This method can be used to get multiple groups in one go. For example, one might query
-     * the top following pages, outlinks and downloads in one go by using log_action.type as
-     * the partition column and [TYPE_ACTION_URL, TYPE_OUTLINK, TYPE_DOWNLOAD] as the possible
-     * values.
-     * When this method has been used, generate() returns as array that contains one array
-     * per group of data.
+     * This method can be used to parition the result based on the possible values of one
+     * table column. This means the query will split the result set into other sets of rows
+     * for each possible value you provide (where the rows of each set have a column value
+     * that equals a possible value). Each of these new sets of rows will be individually
+     * limited resulting in several limited result sets.
+     * 
+     * For example, you can run a query aggregating some data on the log_action table and
+     * partition by log_action.type with the possible values of [TYPE_ACTION_URL](#),
+     * [TYPE_OUTLINK](#), [TYPE_DOWNLOAD](#). The result will be three separate result sets
+     * that are aggregated the same ways, but for rows where `log_action.type = TYPE_OUTLINK`,
+     * for rows where `log_action.type = TYPE_ACTION_URL` and for rows `log_action.type = TYPE_DOWNLOAD`.
      *
-     * @param $partitionColumn string
-     * @param $possibleValues array of integers
-     * @throws Exception when method is used more than once
+     * @param $partitionColumn string The column name to partion by.
+     * @param $possibleValues Array of possible column values.
+     * @throws Exception if method is used more than once.
      */
     public function partitionResultIntoMultipleGroups($partitionColumn, $possibleValues)
     {
@@ -198,13 +204,15 @@ class RankingQuery
     }
 
     /**
-     * Execute the query.
+     * Executes the query.
      * The object has to be configured first using the other methods.
      *
-     * @param $innerQuery string  The "payload" query. The result has be sorted as desired.
+     * @param $innerQuery string  The "payload" query that does the actual data aggregation. The ordering
+     *                            has to be specified in this query. [RankingQuery](#) cannot apply ordering
+     *                            itself.
      * @param $bind array         Bindings for the inner query.
      * @return array              The format depends on which methods have been used
-     *                            to configure the ranking query
+     *                            to configure the ranking query.
      */
     public function execute($innerQuery, $bind = array())
     {
@@ -254,11 +262,13 @@ class RankingQuery
 
     /**
      * Generate the SQL code that does the magic.
-     * If you want to get the result, use execute() instead. If you're interested in
-     * the generated SQL code (e.g. for debugging), use this method.
+     * If you want to get the result, use execute() instead. If you want to run the query
+     * yourself, use this method.
      *
-     * @param $innerQuery string  SQL of the actual query
-     * @return string             entire ranking query SQL
+     * @param $innerQuery string  The "payload" query that does the actual data aggregation. The ordering
+     *                            has to be specified in this query. [RankingQuery](#) cannot apply ordering
+     *                            itself.
+     * @return string             The entire ranking query SQL.
      */
     public function generateQuery($innerQuery)
     {
@@ -362,4 +372,4 @@ class RankingQuery
 			END
 		";
     }
-}
+}
\ No newline at end of file