Refs matomo-org#4200, document rest of DataTable filters.

core/DataTable/Filter/Pattern.php

@@ -14,12 +14,16 @@
 use Piwik\DataTable\Filter;
 
 /**
- * Delete all rows for which the given $columnToFilter do not contain the $patternToSearch
- * This filter is to be used on columns containing strings.
- * Example: from the keyword report, keep only the rows for which the label contains "piwik"
+ * Deletes every row for which a specific column does not match a supplied regex pattern.
+ * 
+ * **Example**
+ * 
+ *     // filter out all rows whose labels doesn't start with piwik
+ *     $dataTable->filter('Pattern', array('label', '^piwik'));
  *
  * @package Piwik
  * @subpackage DataTable
+ * @api
  */
 class Pattern extends Filter
 {
@@ -29,10 +33,13 @@ class Pattern extends Filter
     private $invertedMatch;
 
     /**
-     * @param DataTable $table
-     * @param string $columnToFilter
-     * @param string $patternToSearch
-     * @param bool $invertedMatch
+     * Constructor.
+     * 
+     * @param DataTable $table The table to eventually filter.
+     * @param string $columnToFilter The column to match with the `$patternToSearch` pattern.
+     * @param string $patternToSearch The regex pattern to use.
+     * @param bool $invertedMatch Whether to invert the pattern or not. If true, will remove
+     *                            rows if they match the pattern.
      */
     public function __construct($table, $columnToFilter, $patternToSearch, $invertedMatch = false)
     {
@@ -48,6 +55,7 @@ public function __construct($table, $columnToFilter, $patternToSearch, $inverted
      *
      * @param string $pattern
      * @return string
+     * @ignore
      */
     static public function getPatternQuoted($pattern)
     {
@@ -62,13 +70,16 @@ static public function getPatternQuoted($pattern)
      * @param string $string
      * @param bool $invertedMatch
      * @return int
+     * @ignore
      */
     static public function match($pattern, $patternQuoted, $string, $invertedMatch)
     {
         return @preg_match($patternQuoted . "i", $string) == 1 ^ $invertedMatch;
     }
 
     /**
+     * See [Pattern](#).
+     * 
      * @param DataTable $table
      */
     public function filter($table)
@@ -87,4 +98,4 @@ public function filter($table)
             }
         }
     }
-}
+}

core/DataTable/Filter/PatternRecursive.php

@@ -16,15 +16,17 @@
 use Piwik\DataTable\Manager;
 
 /**
- * Delete all rows for which
- * - the given $columnToFilter do not contain the $patternToSearch
- * - AND all the subTables associated to this row do not contain the $patternToSearch
- *
- * This filter is to be used on columns containing strings.
- * Example: from the pages viewed report, keep only the rows that contain "piwik" or for which a subpage contains "piwik".
+ * Deletes rows for which a specific column in both the row and all subtables that
+ * descend from the row do not match a supplied regex pattern.
+ * 
+ * **Example**
+ * 
+ *     // only display index pageviews in Actions.getPageUrls
+ *     $dataTable->filter('PatternRecursive', array('label', 'index'));
  *
  * @package Piwik
  * @subpackage DataTable
+ * @api
  */
 class PatternRecursive extends Filter
 {
@@ -33,9 +35,11 @@ class PatternRecursive extends Filter
     private $patternToSearchQuoted;
 
     /**
-     * @param DataTable $table
-     * @param string $columnToFilter
-     * @param string $patternToSearch
+     * Constructor.
+     * 
+     * @param DataTable $table The table to eventually filter.
+     * @param string $columnToFilter The column to match with the `$patternToSearch` pattern.
+     * @param string $patternToSearch The regex pattern to use.
      */
     public function __construct($table, $columnToFilter, $patternToSearch)
     {
@@ -47,8 +51,10 @@ public function __construct($table, $columnToFilter, $patternToSearch)
     }
 
     /**
+     * See [PatternRecursive](#).
+     * 
      * @param DataTable $table
-     * @return int
+     * @return int The number of deleted rows.
      */
     public function filter($table)
     {
@@ -83,4 +89,4 @@ public function filter($table)
 
         return $table->getRowsCount();
     }
-}
+}

core/DataTable/Filter/ReplaceColumnNames.php

@@ -18,30 +18,44 @@
 use Piwik\Tracker\GoalManager;
 
 /**
- * This filter replaces column names using a mapping table that maps from the old name to the new name.
- *
- * Why this filter?
- * For saving bytes in the database, you can change all the columns labels by an integer value.
- * Exemple instead of saving 10000 rows with the column name 'nb_uniq_visitors' which would cost a lot of memory,
- * we map it to the integer 1 before saving in the DB.
- * After selecting the DataTable from the DB though, you need to restore back the real names so that
- * it shows nicely in the report (XML for example).
- *
- * You can specify the mapping array to apply in the constructor.
- *
+ * Replaces column names in each row of a table using an array that maps old column
+ * names new ones.
+ * 
+ * If no mapping is provided, this column will use one that maps index metric names
+ * (which are integers) with their string column names. In the database, reports are
+ * stored with integer metric names because it results in blobs that take up less space.
+ * When loading the reports, the column names must be replaced, which is handled by this
+ * class. (See [Metrics](#) for more information about integer metric names.)
+ * 
+ * **Basic example**
+ * 
+ *     // filter use in a plugin's API method
+ *     public function getMyReport($idSite, $period, $date, $segment = false, $expanded = false)
+ *     {
+ *         $dataTable = Archive::getDataTableFromArchive('MyPlugin_MyReport', $idSite, $period, $date, $segment, $expanded);
+ *         $dataTable->queueFilter('ReplaceColumnNames');
+ *         return $dataTable;
+ *     }
+ * 
  * @package Piwik
  * @subpackage DataTable
+ * @api
  */
 class ReplaceColumnNames extends Filter
 {
     protected $mappingToApply;
 
     /**
-     * @param DataTable $table Table
-     * @param array $mappingToApply Mapping to apply. Must have the format
-     *                                           array( OLD_COLUMN_NAME => NEW_COLUMN NAME,
-     *                                                  OLD_COLUMN_NAME2 => NEW_COLUMN NAME2,
-     *                                                 )
+     * Constructor.
+     * 
+     * @param DataTable $table The table that will be eventually filtered.
+     * @param array|null $mappingToApply The name mapping to apply. Must map old column names
+     *                                   with new ones, eg,
+     *                                   ```
+     *                                   array('OLD_COLUMN_NAME' => 'NEW_COLUMN NAME',
+     *                                         'OLD_COLUMN_NAME2' => 'NEW_COLUMN NAME2')
+     *                                   ```
+     *                                   If null, [Metrics::$mappingFromIdToName](#) is used.
      */
     public function __construct($table, $mappingToApply = null)
     {
@@ -53,7 +67,7 @@ public function __construct($table, $mappingToApply = null)
     }
 
     /**
-     * Executes the filter and renames the defined columns
+     * See [ReplaceColumnNames](#).
      *
      * @param DataTable $table
      */
@@ -158,4 +172,4 @@ protected function flattenGoalColumns($columnValue)
         }
         return $newSubColumns;
     }
-}
+}

core/DataTable/Filter/ReplaceSummaryRowLabel.php

@@ -16,15 +16,30 @@
 use Piwik\Piwik;
 
 /**
- *
+ * Replaces the label of the summary row with a supplied label.
+ * 
+ * This filter is only used to prettify the summary row label and so it should
+ * always be queued on a DataTable.
+ * 
+ * This filter always recurses. In other words, this filter will apply itself to
+ * all subtables in the given DataTable's hierarchy.
+ * 
+ * **Basic example**
+ * 
+ *     $dataTable->queueFilter('ReplaceSummaryRowLabel', array(Piwik::translate('General_Others')));
+ * 
  * @package Piwik
  * @subpackage DataTable
+ * @api
  */
 class ReplaceSummaryRowLabel extends Filter
 {
     /**
-     * @param DataTable $table
-     * @param string|null $newLabel new label for summary row
+     * Constructor.
+     * 
+     * @param DataTable $table The table that will eventually be filtered.
+     * @param string|null $newLabel The new label for summary row. If null, defaults to
+     *                              `Piwik::translate('General_Others')`.
      */
     public function __construct($table, $newLabel = null)
     {
@@ -36,7 +51,7 @@ public function __construct($table, $newLabel = null)
     }
 
     /**
-     * Updates the summary row label
+     * See [ReplaceSummaryRowLabel](#).
      *
      * @param DataTable $table
      */

core/DataTable/Filter/SafeDecodeLabel.php

@@ -14,6 +14,8 @@
 use Piwik\DataTable\Filter;
 
 /**
+ * Sanitizes DataTable labels as an extra precaution. Called internally by Piwik.
+ * 
  * @package Piwik
  * @subpackage DataTable
  */
@@ -71,4 +73,4 @@ public function filter($table)
             }
         }
     }
-}
+}

core/DataTable/Filter/Sort.php

@@ -17,23 +17,26 @@
 use Piwik\Metrics;
 
 /**
- * Sort the DataTable based on the value of column $columnToSort ordered by $order.
+ * Sorts a DataTable based on the value of a specific column.
  * Possible to specify a natural sorting (see php.net/natsort for details)
  *
  * @package Piwik
  * @subpackage DataTable
+ * @api
  */
 class Sort extends Filter
 {
     protected $columnToSort;
     protected $order;
 
     /**
-     * @param DataTable $table
-     * @param string $columnToSort name of the column to sort by
-     * @param string $order order (asc|desc)
-     * @param bool $naturalSort use natural sort?
-     * @param bool $recursiveSort sort recursively?
+     * Constructor.
+     * 
+     * @param DataTable $table The table to eventually filter.
+     * @param string $columnToSort The name of the column to sort by.
+     * @param string $order order `'asc'` or `'desc'`.
+     * @param bool $naturalSort Whether to use a natural sort or not (see [http://php.net/natsort](#http://php.net/natsort)).
+     * @param bool $recursiveSort Whether to sort all subtables or not.
      */
     public function __construct($table, $columnToSort, $order = 'desc', $naturalSort = true, $recursiveSort = false)
     {
@@ -218,4 +221,4 @@ public function filter($table)
         }
         $table->sort(array($this, $methodToUse), $this->columnToSort);
     }
-}
+}