Refs #4200, documented core/Plugin/API, core/Plugin/Archiver and part of core/Plugin/Controller.

4 files changed, 138 insertions, 38 deletions

diff --git a/core/Plugin/API.php b/core/Plugin/API.php
index 436f13a32c..474b73fa29 100644
--- a/core/Plugin/API.php
+++ b/core/Plugin/API.php
@@ -20,9 +20,11 @@ use Piwik\Singleton;
  * that derives from this one. Every public method in that class will be callable
  * through Piwik's API.
  * 
- * ### Example
+ * ### Examples
  * 
- *     class MyAPI extends API
+ * **Defining an API for a plugin**
+ * 
+ *     class API extends \Piwik\Plugin\API
  *     {
  *         public function myMethod($idSite, $period, $date, $segment = false)
  *         {
@@ -31,6 +33,10 @@ use Piwik\Singleton;
  *         }
  *     }
  * 
+ * **Linking to an API method**
+ * 
+ *     <a href="?module=API&method=MyPlugin.myMethod&idSite=1&period=day&date=2013-10-23">Link</a>
+ * 
  * @api
  */
 abstract class API extends Singleton
diff --git a/core/Plugin/Archiver.php b/core/Plugin/Archiver.php
index 97dc987f42..b1bb8d68e7 100644
--- a/core/Plugin/Archiver.php
+++ b/core/Plugin/Archiver.php
@@ -15,15 +15,66 @@ use Piwik\ArchiveProcessor;
 use Piwik\Config as PiwikConfig;
 
 /**
- * Plugins that archive metrics for websites can implement an Archiver that extends this class
+ * The base class that should be extended by plugins that archive their own
+ * metrics.
+ * 
+ * ### Examples
+ * 
+ * **Extending Archiver**
+ * 
+ *     class MyArchiver extends Archiver
+ *     {
+ *         public function archiveDay()
+ *         {
+ *             $logAggregator = $this->getLogAggregator();
+ *             
+ *             $data = $logAggregator->queryVisitsByDimension(...);
+ *             
+ *             $dataTable = new DataTable();
+ *             $dataTable->addRowsFromSimpleArray($data);
+ * 
+ *             $archiveProcessor = $this->getProcessor();
+ *             $archiveProcessor->insertBlobRecords('MyPlugin_myReport', $dataTable->getSerialized(500));
+ *         }
+ *         
+ *         public function archivePeriod()
+ *         {
+ *             $archiveProcessor = $this->getProcessor();
+ *             $archiveProcessor->aggregateDataTableReports('MyPlugin_myReport', 500);
+ *         }
+ *     }
+ * 
+ * **Using Archiver in archiving events**
+ * 
+ *     // event observer for ArchiveProcessor.Day.compute
+ *     public function archiveDay(ArchiveProcessor\Day $archiveProcessor)
+ *     {
+ *         $archiving = new Archiver($archiveProcessor);
+ *         if ($archiving->shouldArchive()) {
+ *             $archiving->archiveDay();
+ *         }
+ *     }
+ * 
+ *     // event observer for ArchiveProcessor.Period.compute
+ *     public function archivePeriod(ArchiveProcessor\Period $archiveProcessor)
+ *     {
+ *         $archiving = new Archiver($archiveProcessor);
+ *         if ($archiving->shouldArchive()) {
+ *             $archiving->archivePeriod();
+ *         }
+ *     }
+ * 
+ * @api
  */
 abstract class Archiver
 {
     protected $processor;
 
     /**
-     * Constructor
-     * @param ArchiveProcessor $processing
+     * Constructor.
+     * 
+     * @param ArchiveProcessor $processing The ArchiveProcessor instance sent to the archiving
+     *                                     event observer.
      */
     public function __construct(ArchiveProcessor $processing)
     {
@@ -31,11 +82,22 @@ abstract class Archiver
         $this->processor = $processing;
     }
 
+    /**
+     * Archive data for a day period.
+     */
     abstract public function archiveDay();
 
+    /**
+     * Archive data for a non-day period.
+     */
     abstract public function archivePeriod();
 
     // todo: review this concept, each plugin should somehow maintain the list of report names they generate
+    /**
+     * Returns true if the current plugin should be archived or not.
+     * 
+     * @return bool
+     */
     public function shouldArchive()
     {
         $className = get_class($this);
@@ -61,4 +123,4 @@ abstract class Archiver
     {
         return $this->getProcessor()->getLogAggregator();
     }
-}
+}
\ No newline at end of file
diff --git a/core/Plugin/ConsoleCommand.php b/core/Plugin/ConsoleCommand.php
index 132009d1bc..7dbdf36557 100644
--- a/core/Plugin/ConsoleCommand.php
+++ b/core/Plugin/ConsoleCommand.php
@@ -15,7 +15,8 @@ use Symfony\Component\Console\Command\Command as SymfonyCommand;
 use Symfony\Component\Console\Output\OutputInterface;
 
 /**
- * BaseClass for console commands.
+ * The base class for console commands.
+ * 
  * @package Piwik_Console
  */
 class ConsoleCommand extends SymfonyCommand
@@ -46,4 +47,4 @@ class ConsoleCommand extends SymfonyCommand
         $output->writeln('<info>' . $separator . '</info>');
         $output->writeln('');
     }
-}
+}
\ No newline at end of file
diff --git a/core/Plugin/Controller.php b/core/Plugin/Controller.php
index 6d6f61a8c4..93a6add8e2 100644
--- a/core/Plugin/Controller.php
+++ b/core/Plugin/Controller.php
@@ -32,49 +32,78 @@ use Piwik\SettingsPiwik;
 use Piwik\Site;
 use Piwik\Url;
 use Piwik\View;
+use Piwik\View\ViewInterface;
 use Piwik\ViewDataTable\Factory as ViewDataTableFactory;
 
 /**
- * Parent class of all plugins Controllers (located in /plugins/PluginName/Controller.php
- * It defines some helper functions controllers can use.
+ * Base class of all plugin Controllers.
+ * 
+ * Plugins that wish to add display HTML should create a Controller that either
+ * extends from this class or from [ControllerAdmin](#). Every public method in
+ * the controller will be exposed as a controller action.
+ * 
+ * Learn more about Piwik's MVC system [here](#).
+ * 
+ * ### Examples
+ * 
+ * **Defining a controller**
+ * 
+ *     class Controller extends \Piwik\Plugin\Controller
+ *     {
+ *         public function index()
+ *         {
+ *             $view = new View("@MyPlugin/index.twig");
+ *             // ... setup view ...
+ *             echo $view->render();
+ *         }
+ *     }
+ * 
+ * **Linking to a controller action**
  *
+ *     <a href="?module=MyPlugin&action=index&idSite=1&period=day&date=2013-10-10">Link</a>
+ * 
  * @package Piwik
  * @api
  */
 abstract class Controller
 {
     /**
-     * Plugin name, eg. Referrers
+     * The plugin name, eg. `'Referrers'`.
+     * 
      * @var string
      */
     protected $pluginName;
 
     /**
-     * Date string
+     * The value of the `'date'` query parameter.
      *
      * @var string
      */
     protected $strDate;
 
     /**
-     * Date object or null if the requested date is a range
+     * The Date object created with ($strDate)[#strDate] or null if the requested date is a range.
      *
      * @var Date|null
      */
     protected $date;
 
     /**
+     * The value of the `'idSite'` query parameter.
+     * 
      * @var int
      */
     protected $idSite;
 
     /**
+     * The Site object created with ($idSite)[#idSite].
+     * 
      * @var Site
      */
     protected $site = null;
 
     /**
-     * Builds the controller object, reads the date from the request, extracts plugin name from
+     * Constructor.
      */
     public function __construct()
     {
@@ -99,16 +128,16 @@ abstract class Controller
     }
 
     /**
-     * Helper method to convert "today" or "yesterday" to the default timezone specified.
-     * If the date is absolute, ie. YYYY-MM-DD, it will not be converted to the timezone
+     * Helper method that converts "today" or "yesterday" to the specified timezone.
+     * If the date is absolute, ie. YYYY-MM-DD, it will not be converted to the timezone.
      *
      * @param string $date today, yesterday, YYYY-MM-DD
-     * @param string $defaultTimezone default timezone to use
+     * @param string $timezone default timezone to use
      * @return Date
      */
-    protected function getDateParameterInTimezone($date, $defaultTimezone)
+    protected function getDateParameterInTimezone($date, $timezone)
     {
-        $timezone = null;
+        $timezoneToUse = null;
         // if the requested date is not YYYY-MM-DD, we need to ensure
         //  it is relative to the website's timezone
         if (in_array($date, array('today', 'yesterday'))) {
@@ -120,28 +149,28 @@ abstract class Controller
             } elseif ($date == 'yesterday') {
                 $date = 'yesterdaySameTime';
             }
-            $timezone = $defaultTimezone;
+            $timezoneToUse = $timezone;
         }
-        return Date::factory($date, $timezone);
+        return Date::factory($date, $timezoneToUse);
     }
 
     /**
      * Sets the date to be used by all other methods in the controller.
-     * If the date has to be modified, it should be called just after the controller construct
+     * If the date has to be modified, this method should be called just after
+     * construction.
      *
-     * @param Date $date
+     * @param Date $date The new Date.
      * @return void
      */
     protected function setDate(Date $date)
     {
         $this->date = $date;
-        $strDate = $this->date->toString();
-        $this->strDate = $strDate;
+        $this->strDate = $date->toString();
     }
 
     /**
      * Returns the name of the default method that will be called
-     * when visiting: index.php?module=PluginName without the action parameter
+     * when visiting: index.php?module=PluginName without the action parameter.
      *
      * @return string
      */
@@ -151,15 +180,14 @@ abstract class Controller
     }
 
     /**
-     * Given an Object implementing ViewInterface, we either:
-     * - echo the output of the rendering if fetch = false
-     * - returns the output of the rendering if fetch = true
+     * A helper method that renders a view either to the screen or to a string.
      *
-     * @param ViewDataTable $view view object to use
-     * @param bool $fetch indicates whether to output or return the content
+     * @param ViewInterface $view The view to render.
+     * @param bool $fetch If true, the result is returned as a string. If false,
+     *                    the rendered string is echo'd to the screen.
      * @return string|void
      */
-    protected function renderView(ViewDataTable $view, $fetch = false)
+    protected function renderView(ViewInterface $view, $fetch = false)
     {
         $rendered = $view->render();
         if ($fetch) {
@@ -169,12 +197,14 @@ abstract class Controller
     }
 
     /**
-     * Returns a ViewDataTable object of an Evolution graph
+     * Returns a ViewDataTable object that will render a jqPlot evolution graph
      * for the last30 days/weeks/etc. of the current period, relative to the current date.
      *
-     * @param string $currentModuleName
-     * @param string $currentControllerAction
-     * @param string $apiMethod
+     * @param string $currentModuleName The name of the current plugin.
+     * @param string $currentControllerAction The name of the action that renders the desired
+     *                                        report.
+     * @param string $apiMethod The API method that the ViewDataTable will use to get
+     *                          graph data.
      * @return ViewDataTable
      */
     protected function getLastUnitGraph($currentModuleName, $currentControllerAction, $apiMethod)
@@ -199,8 +229,9 @@ abstract class Controller
      *                                (by default, this is API.get but it can be changed for custom stuff)
      * @return ViewDataTable
      */
-    protected function getLastUnitGraphAcrossPlugins($currentModuleName, $currentControllerAction,
-                                                     $columnsToDisplay, $selectableColumns = array(), $reportDocumentation = false, $apiMethod = 'API.get')
+    protected function getLastUnitGraphAcrossPlugins($currentModuleName, $currentControllerAction, $columnsToDisplay,
+                                                     $selectableColumns = array(), $reportDocumentation = false,
+                                                     $apiMethod = 'API.get')
     {
         // load translations from meta data
         $idSite = Common::getRequestVar('idSite');