Refs #4200 fixing build and documented AddColumnsProcessedMetricsGoal.

1 files changed, 38 insertions, 17 deletions

diff --git a/core/DataTable/Filter/AddColumnsProcessedMetricsGoal.php b/core/DataTable/Filter/AddColumnsProcessedMetricsGoal.php
index 51fe770217..cf2f5b4429 100644
--- a/core/DataTable/Filter/AddColumnsProcessedMetricsGoal.php
+++ b/core/DataTable/Filter/AddColumnsProcessedMetricsGoal.php
@@ -17,8 +17,35 @@ use Piwik\Piwik;
 use Piwik\Tracker\GoalManager;
 
 /**
+ * Adds the following columns to a DataTable using metrics that already exist:
+ * 
+ * - **revenue_per_visit**: total goal and ecommerce revenue / nb_visits
+ * - **goal_%idGoal%_conversion_rate**: the conversion rate. There will be one of
+ *                                      these columns for each goal that exists
+ *                                      for the site.
+ * - **goal_%idGoal%_nb_conversions**: the number of conversions. There will be one of
+ *                                     these columns for each goal that exists
+ *                                     for the site.
+ * - **goal_%idGoal%_revenue_per_visit**: goal revenue / nb_visits. There will be one of
+ *                                        these columns for each goal that exists
+ *                                        for the site.
+ * - **goal_%idGoal%_revenue**: goal revenue. There will be one of
+ *                              these columns for each goal that exists
+ *                              for the site.
+ * - **goal_%idGoal%_avg_order_revenue**: goal revenue / number of orders or abandoned
+ *                                        carts. Only for ecommerce order and abandoned cart
+ *                                        reports.
+ * - **goal_%idGoal%_items**: number of items. Only for ecommerce order and abandoned cart
+ *                            reports.
+ * 
+ * Adding the **filter_update_columns_when_show_all_goals** query parameter to
+ * an API request will trigger the execution of this Filter.
+ * 
+ * Note: This filter must be called before [ReplaceColumnNames](#) is called.
+ * 
  * @package Piwik
  * @subpackage DataTable
+ * @api
  */
 class AddColumnsProcessedMetricsGoal extends AddColumnsProcessedMetrics
 {
@@ -38,21 +65,14 @@ class AddColumnsProcessedMetricsGoal extends AddColumnsProcessedMetrics
     const GOALS_FULL_TABLE = 0;
 
     /**
-     * Adds processed goal metrics to a table:
-     * - global conversion rate,
-     * - global revenue per visit.
-     * Can also process per-goal metrics:
-     * - conversion rate
-     * - nb conversions
-     * - revenue per visit
-     *
-     * @param DataTable $table
-     * @param bool $enable should be true (automatically set to true when filter_update_columns_when_show_all_goals is found in the API request)
-     * @param string $processOnlyIdGoal Defines what metrics to add (don't process metrics when you don't display them)
-     *                                             If self::GOALS_FULL_TABLE, all Goal metrics (and per goal metrics) will be processed
-     *                                             If self::GOALS_OVERVIEW, only the main goal metrics will be added
-     *                                             If an int > 0, then will process only metrics for this specific Goal
-     * @return \Piwik\DataTable\Filter\AddColumnsProcessedMetricsGoal
+     * Constructor.
+     * 
+     * @param DataTable $table The table that will eventually filtered.
+     * @param bool $enable Always set to true.
+     * @param string $processOnlyIdGoal Defines what metrics to add (don't process metrics when you don't display them).
+     *                                  If self::GOALS_FULL_TABLE, all Goal metrics (and per goal metrics) will be processed.
+     *                                  If self::GOALS_OVERVIEW, only the main goal metrics will be added.
+     *                                  If an int > 0, then will process only metrics for this specific Goal.
      */
     public function __construct($table, $enable = true, $processOnlyIdGoal)
     {
@@ -64,7 +84,8 @@ class AddColumnsProcessedMetricsGoal extends AddColumnsProcessedMetrics
     }
 
     /**
-     * Filters the given data table
+     * Adds the processed metrics. See [AddColumnsProcessedMetrics](#AddColumnsProcessedMetrics) for
+     * more information.
      *
      * @param DataTable $table
      */
@@ -200,4 +221,4 @@ class AddColumnsProcessedMetricsGoal extends AddColumnsProcessedMetrics
             }
         }
     }
-}
+}
\ No newline at end of file