#2373 inline documentation for reports and metrics

git-svn-id: http://dev.piwik.org/svn/trunk@4634 59fd770c-687e-43c8-a1e3-f5a4ff64c105

3 files changed, 47 insertions, 29 deletions

diff --git a/plugins/VisitsSummary/API.php b/plugins/VisitsSummary/API.php
index 7c252c900f..8a3adaf82c 100644
--- a/plugins/VisitsSummary/API.php
+++ b/plugins/VisitsSummary/API.php
@@ -1,22 +1,22 @@
 <?php
 /**
  * Piwik - Open source web analytics
- * 
+ *
  * @link http://piwik.org
  * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
  * @version $Id$
- * 
+ *
  * @category Piwik_Plugins
  * @package Piwik_VisitsSummary
  */
 
 /**
- * VisitsSummary API lets you access the core web analytics metrics (visits, unique visitors, 
+ * VisitsSummary API lets you access the core web analytics metrics (visits, unique visitors,
  * count of actions (page views & downloads & clicks on outlinks), time on site, bounces and converted visits.
- * 
+ *
  * @package Piwik_VisitsSummary
  */
-class Piwik_VisitsSummary_API 
+class Piwik_VisitsSummary_API
 {
 	static private $instance = null;
 	static public function getInstance()
@@ -56,10 +56,10 @@ class Piwik_VisitsSummary_API
 		else
 		{
     		$bounceRateRequested = $actionsPerVisitRequested = $averageVisitDurationRequested = true;
-			$columns = array(	
+			$columns = array(
 								'nb_visits',
-								'nb_uniq_visitors', 
-								'nb_actions', 
+								'nb_uniq_visitors',
+								'nb_actions',
 								'nb_visits_converted',
 								'bounce_count',
 								'sum_visit_length',
@@ -89,11 +89,11 @@ class Piwik_VisitsSummary_API
 			$dataTable->filter('ColumnCallbackAddColumnQuotient', array('avg_time_on_site', 'sum_visit_length', 'nb_visits', 0));
 		}
 		
-		// If only a computed metrics was requested, we delete other metrics 
-		// that we selected only to process this one metric 
+		// If only a computed metrics was requested, we delete other metrics
+		// that we selected only to process this one metric
 		if($countColumnsRequested == 1
 			&& ($bounceRateRequested || $actionsPerVisitRequested || $averageVisitDurationRequested)
-			) 
+			)
 		{
 			$dataTable->deleteColumns($columns);
 		}
@@ -105,7 +105,7 @@ class Piwik_VisitsSummary_API
 		Piwik::checkUserHasViewAccess( $idSite );
 		$archive = Piwik_Archive::build($idSite, $period, $date, $segment );
 		$dataTable = $archive->getNumeric($toFetch);
-		return $dataTable;		
+		return $dataTable;
 	}
 
 	public function getVisits( $idSite, $period, $date, $segment = false )
diff --git a/plugins/VisitsSummary/Controller.php b/plugins/VisitsSummary/Controller.php
index f3a757c85a..c11a2e930f 100644
--- a/plugins/VisitsSummary/Controller.php
+++ b/plugins/VisitsSummary/Controller.php
@@ -1,11 +1,11 @@
 <?php
 /**
  * Piwik - Open source web analytics
- * 
+ *
  * @link http://piwik.org
  * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
  * @version $Id$
- * 
+ *
  * @category Piwik_Plugins
  * @package Piwik_VisitsSummary
  */
@@ -14,14 +14,14 @@
  *
  * @package Piwik_VisitsSummary
  */
-class Piwik_VisitsSummary_Controller extends Piwik_Controller 
+class Piwik_VisitsSummary_Controller extends Piwik_Controller
 {
 	public function index()
 	{
 		$view = Piwik_View::factory('index');
 		$this->setPeriodVariablesView($view);
 		$view->graphEvolutionVisitsSummary = $this->getEvolutionGraph( true, array('nb_visits') );
-		$this->setSparklinesAndNumbers($view);		
+		$this->setSparklinesAndNumbers($view);
 		echo $view->render();
 	}
 	
@@ -29,7 +29,7 @@ class Piwik_VisitsSummary_Controller extends Piwik_Controller
 	{
 		$view = Piwik_View::factory('sparklines');
 		$this->setPeriodVariablesView($view);
-		$this->setSparklinesAndNumbers($view);		
+		$this->setSparklinesAndNumbers($view);
 		echo $view->render();
 	}
 
@@ -42,6 +42,24 @@ class Piwik_VisitsSummary_Controller extends Piwik_Controller
 		}
 		$columns = !is_array($columns) ? array($columns) : $columns;
 		$view->setColumnsToDisplay($columns);
+		
+		$doc = Piwik_Translate('VisitsSummary_VisitsSummaryDocumentation').'<br />'
+		     . Piwik_Translate('General_BrokenDownReportDocumentation').'<br /><br />'
+		     
+		     . '<b>'.Piwik_Translate('General_ColumnNbVisits').':</b> '
+		     . Piwik_Translate('General_ColumnNbVisitsDocumentation').'<br />'
+		     
+		     . '<b>'.Piwik_Translate('General_ColumnNbUniqVisitors').':</b> '
+		     . Piwik_Translate('General_ColumnNbUniqVisitorsDocumentation').'<br />'
+		     
+		     . '<b>'.Piwik_Translate('General_ColumnNbActions').':</b> '
+		     . Piwik_Translate('General_ColumnNbActionsDocumentation').'<br />'
+		     
+		     . '<b>'.Piwik_Translate('General_ColumnActionsPerVisit').':</b> '
+		     . Piwik_Translate('General_ColumnActionsPerVisitDocumentation');
+		
+		$view->setReportDocumentation($doc);
+		
 		return $this->renderView($view, $fetch);
 	}
 
@@ -49,9 +67,9 @@ class Piwik_VisitsSummary_Controller extends Piwik_Controller
 	{
 		$requestString =	"method=VisitsSummary.get".
 							"&format=original".
-							// we disable filters for example "search for pattern", in the case this method is called 
-							// by a method that already calls the API with some generic filters applied 
-							"&disable_generic_filters=1"; 
+							// we disable filters for example "search for pattern", in the case this method is called
+							// by a method that already calls the API with some generic filters applied
+							"&disable_generic_filters=1";
 		$request = new Piwik_API_Request($requestString);
 		return $request->process();
 	}
@@ -60,7 +78,7 @@ class Piwik_VisitsSummary_Controller extends Piwik_Controller
 	{
 		$requestString = 	"method=VisitsSummary.getVisits".
 							"&format=original".
-							"&disable_generic_filters=1"; 
+							"&disable_generic_filters=1";
 		$request = new Piwik_API_Request($requestString);
 		return $request->process();
 	}
diff --git a/plugins/VisitsSummary/VisitsSummary.php b/plugins/VisitsSummary/VisitsSummary.php
index 9b4cd8939d..20303a27da 100644
--- a/plugins/VisitsSummary/VisitsSummary.php
+++ b/plugins/VisitsSummary/VisitsSummary.php
@@ -1,21 +1,21 @@
 <?php
 /**
  * Piwik - Open source web analytics
- * 
+ *
  * @link http://piwik.org
  * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
  * @version $Id$
- * 
+ *
  * @category Piwik_Plugins
  * @package Piwik_VisitsSummary
  */
 
 /**
- * Note: This plugin does not hook on Daily and Period Archiving like other Plugins because it reports the 
+ * Note: This plugin does not hook on Daily and Period Archiving like other Plugins because it reports the
  * very core metrics (visits, actions, visit duration, etc.) which are processed in the Core
- * Piwik_ArchiveProcessing_Day class directly. 
+ * Piwik_ArchiveProcessing_Day class directly.
  * These metrics can be used by other Plugins so they need to be processed up front.
- * 
+ *
  * @package Piwik_VisitsSummary
  */
 class Piwik_VisitsSummary extends Piwik_Plugin
@@ -40,7 +40,7 @@ class Piwik_VisitsSummary extends Piwik_Plugin
 		);
 	}
 	
-	public function getReportMetadata($notification) 
+	public function getReportMetadata($notification)
 	{
 		$reports = &$notification->getNotificationObject();
 		$reports[] = array(
@@ -49,9 +49,9 @@ class Piwik_VisitsSummary extends Piwik_Plugin
 			'module' => 'VisitsSummary',
 			'action' => 'get',
 			'metrics' => array(
-								'nb_uniq_visitors', 
+								'nb_uniq_visitors',
 								'nb_visits',
-								'nb_actions', 
+								'nb_actions',
 								'nb_actions_per_visit',
 								'bounce_rate',
 								'avg_time_on_site' => Piwik_Translate('General_VisitDuration'),