Refs #4200, documented undocumented visualization classes.

3 files changed, 83 insertions, 10 deletions

diff --git a/core/ViewDataTable/Config.php b/core/ViewDataTable/Config.php
index ee576a6d5b..1a8d5a21c5 100644
--- a/core/ViewDataTable/Config.php
+++ b/core/ViewDataTable/Config.php
@@ -15,8 +15,8 @@ use Piwik\Metrics;
 use Piwik\Plugins\API\API;
 
 /**
- * Contains base display properties for ViewDataTables. Manipulating these properties
- * in a ViewDataTable instance will change how its report will be displayed.
+ * Contains base display properties for {@link Piwik\Plugin\ViewDataTable}s. Manipulating these
+ * properties in a ViewDataTable instance will change how its report will be displayed.
  * 
  * <a name="client-side-properties-desc"></a>
  * **Client Side Properties**
@@ -31,6 +31,16 @@ use Piwik\Plugins\API\API;
  * If a request has a query parameter that matches an overridable property, the property
  * will be set to the query parameter value.
  * 
+ * **Reusing base properties**
+ * 
+ * Many of the properties in this class only have meaning for the {@link Piwik\Plugin\Visualization}
+ * class, but can be set for other visualizations that extend {@link Piwik\Plugin\ViewDataTable} 
+ * directly.
+ * 
+ * Visualizations that extend {@link Piwik\Plugin\ViewDataTable} directly and want to re-use these
+ * properties must make sure the properties are used in the exact same way they are used in
+ * {@link Piwik\Plugin\Visualization}.
+ * 
  * **Defining new display properties**
  * 
  * If you are creating your own visualization and want to add new display properties for
@@ -394,17 +404,17 @@ class Config
     public $export_limit = '';
 
     /**
-     * TODO
+     * @ignore
      */
     public $report_id = '';
 
     /**
-     * TODO
+     * @ignore
      */
     public $controllerName;
 
     /**
-     * TODO
+     * @ignore
      */
     public $controllerAction;
 
@@ -421,7 +431,7 @@ class Config
     }
 
     /**
-     * TODO
+     * @ignore
      */
     public function setController($controllerName, $controllerAction)
     {
diff --git a/core/ViewDataTable/Factory.php b/core/ViewDataTable/Factory.php
index 0a9510372a..4dd4a15273 100644
--- a/core/ViewDataTable/Factory.php
+++ b/core/ViewDataTable/Factory.php
@@ -28,7 +28,7 @@ use Piwik\Plugins\CoreVisualizations\Visualizations\HtmlTable;
  *         $view = Factory::build('table', 'MyPlugin.myReport');
  *         $view->config->show_limit_control = true;
  *         $view->config->translations['myFancyMetric'] = "My Fancy Metric";
- *         echo $view->render();
+ *         return $view->render();
  *     }
  * 
  * **Displaying a report in another way**
@@ -40,7 +40,7 @@ use Piwik\Plugins\CoreVisualizations\Visualizations\HtmlTable;
  *     {
  *         $view = Factory::build('table', 'MyPlugin.myReport', 'MyPlugin.myReportShownDifferently');
  *         $view->config->filters[] = array('MyMagicFilter', array('an arg', 'another arg'));
- *         echo $view->render();
+ *         return $view->render();
  *     }
  * 
  * **Force a report to be shown as a bar graph**
@@ -52,7 +52,7 @@ use Piwik\Plugins\CoreVisualizations\Visualizations\HtmlTable;
  *     {
  *         $view = Factory::build('graphVerticalBar', 'MyPlugin.myReport', 'MyPlugin.myReportShownAsABarGraph',
  *                                $forceDefault = true);
- *         echo $view->render();
+ *         return $view->render();
  *     }
  * 
  * @package Piwik
diff --git a/core/ViewDataTable/RequestConfig.php b/core/ViewDataTable/RequestConfig.php
index 9f13004639..bc0311f678 100644
--- a/core/ViewDataTable/RequestConfig.php
+++ b/core/ViewDataTable/RequestConfig.php
@@ -13,8 +13,71 @@ namespace Piwik\ViewDataTable;
 use Piwik\Common;
 
 /**
- * TODO
+ * Contains base request properties for {@link Piwik\Plugin\ViewDataTable} instances. Manipulating
+ * these properties will change the way a {@link Piwik\Plugin\ViewDataTable} loads report data.
+ * 
+ * <a name="client-side-parameters-desc"></a>
+ * **Client Side Parameters**
+ * 
+ * Client side parameters are request properties that should be passed on to the browser so
+ * client side JavaScript can use them. These properties will also be passed to the server with
+ * every AJAX request made.
+ * 
+ * Only affects ViewDataTables that output HTML.
+ * 
+ * <a name="overridable-properties-desc"></a>
+ * **Overridable Properties**
  *
+ * Overridable properties are properties that can be set via the query string.
+ * If a request has a query parameter that matches an overridable property, the property
+ * will be set to the query parameter value.
+ * 
+ * **Reusing base properties**
+ * 
+ * Many of the properties in this class only have meaning for the {@link Piwik\Plugin\Visualization}
+ * class, but can be set for other visualizations that extend {@link Piwik\Plugin\ViewDataTable} 
+ * directly.
+ * 
+ * Visualizations that extend {@link Piwik\Plugin\ViewDataTable} directly and want to re-use these
+ * properties must make sure the properties are used in the exact same way they are used in
+ * {@link Piwik\Plugin\Visualization}.
+ * 
+ * **Defining new request properties**
+ * 
+ * If you are creating your own visualization and want to add new request properties for
+ * it, extend this class and add your properties as fields.
+ * 
+ * Properties are marked as client side parameters by calling the
+ * {@link addPropertiesThatShouldBeAvailableClientSide()} method.
+ * 
+ * Properties are marked as overridable by calling the
+ * {@link addPropertiesThatCanBeOverwrittenByQueryParams()} method.
+ *
+ * ### Example
+ * 
+ * **Defining new request properties**
+ * 
+ *     class MyCustomVizRequestConfig extends RequestConfig
+ *     {
+ *         /**
+ *          * My custom property. It is overridable.
+ *          *\/
+ *         public $my_custom_property = false;
+ *
+ *         /**
+ *          * Another custom property. It is available client side.
+ *          *\/
+ *         public $another_custom_property = true;
+ * 
+ *         public function __construct()
+ *         {
+ *             parent::__construct();
+ * 
+ *             $this->addPropertiesThatShouldBeAvailableClientSide(array('another_custom_property'));
+ *             $this->addPropertiesThatCanBeOverwrittenByQueryParams(array('my_custom_property'));
+ *         }
+ *     }
+ * 
  * @package Piwik
  * @subpackage Piwik_Visualization
  * @api