Refs #4200 started documenting LogAggregator and documented Plugin/API.

core/DataAccess/LogAggregator.php

@@ -21,8 +21,14 @@ use Piwik\Site;
 use Piwik\Tracker\GoalManager;
 
 /**
- * This class queries the Visitor logs tables (visits, actions, conversions, ecommerce)
- * and returns aggregate data.
+ * Contains methods that aggregates log data (visits, actions, conversions, ecommerce).
+ * 
+ * Plugin [Archiver](#) descendants can use the methods in this class to aggregate data
+ * in the log tables without creating their own SQL queries.
+ * 
+ * ### Examples
+ * 
+ * ** TODO **
  */
 class LogAggregator
 {
@@ -126,22 +132,36 @@ class LogAggregator
     }
 
     /**
-     * Query visits logs by dimension, and return the aggregate data.
+     * Queries visit logs by dimension and returns the aggregate data.
      *
-     * @param array|string $dimensions Can be a string, eg. "referrer_name", will be aliased as 'label' in the returned rows
-     *                                      Can also be an array of strings, when the dimension spans multiple fields,
-     *                                      eg. array("referrer_name", "referrer_keyword")
-     * @param bool|string $where Additional condition for WHERE clause
-     * @param array $additionalSelects Additional SELECT clause
-     * @param bool|array $metrics Set this if you want to limit the columns that are returned.
-     *                                      The possible values in the array are Metrics::INDEX_*.
+     * @param array|string $dimensions SELECT fields (or just one field) that will be grouped by,
+     *                                 eg, `'referrer_name'` or `array('referrer_name', 'referrer_keyword')`.
+     *                                 The metrics retrieved from the query will be specific to combinations
+     *                                 of these fields. So if `array('referrer_name', 'referrer_keyword')`
+     *                                 is supplied, the query will select the visits for each referrer/keyword
+     *                                 combination.
+     * @param bool|string $where Additional condition for the WHERE clause. Can be used to filter
+     *                           the set of visits that are looked at.
+     * @param array $additionalSelects Additional SELECT fields that are not included in the group by
+     *                                 clause. These can be aggregate expressions, eg, `SUM(somecol)`.
+     * @param bool|array $metrics The set of metrics to return. If false, the query will select all of them.
+     *                            The following values can be used:
+     *                              - Metrics::INDEX_NB_UNIQ_VISITORS
+     *                              - Metrics::INDEX_NB_VISITS
+     *                              - Metrics::INDEX_NB_ACTIONS
+     *                              - Metrics::INDEX_MAX_ACTIONS
+     *                              - Metrics::INDEX_SUM_VISIT_LENGTH
+     *                              - Metrics::INDEX_BOUNCE_COUNT
+     *                              - Metrics::INDEX_NB_VISITS_CONVERTED
      * @param bool|\Piwik\RankingQuery $rankingQuery
-     *                                      A pre-configured ranking query instance that is used to limit the result.
-     *                                      If set, the return value is the array returned by RankingQuery::execute().
-     *
-     * @return mixed
+     *                                   A pre-configured ranking query instance that will be used to limit the result.
+     *                                   If set, the return value is the array returned by [RankingQuery::execute()](#).
+     * @return mixed A Zend_Db_Statement if `$rankingQuery` isn't supplied, otherwise the result of
+     *                                   [RankingQuery::execute()](#).
+     * @api
      */
-    public function queryVisitsByDimension(array $dimensions = array(), $where = false, array $additionalSelects = array(), $metrics = false, $rankingQuery = false)
+    public function queryVisitsByDimension(array $dimensions = array(), $where = false, array $additionalSelects = array(),
+                                           $metrics = false, $rankingQuery = false)
     {
         $tableName = self::LOG_VISIT_TABLE;
         $availableMetrics = $this->getVisitsMetricFields();
@@ -314,7 +334,7 @@ class LogAggregator
     }
 
     /**
-     * Returns the ecommerce items
+     * Queries all ecommerce items.
      *
      * @param string $field
      * @return string
@@ -342,8 +362,7 @@ class LogAggregator
         // $query = $this->query($select, $from, $where, $groupBy, $orderBy);
 
         $bind = $this->getBindDatetimeSite();
-        $query = $this->getDb()->query($query, $bind);
-        return $query;
+        return $this->getDb()->query($query, $bind);
     }
 
     /**

core/Plugin/API.php

@@ -13,7 +13,27 @@ namespace Piwik\Plugin;
 
 use Piwik\Singleton;
 
+/**
+ * The base class of all API singletons.
+ * 
+ * Plugins that want to expose functionality through an API should create a class
+ * that derives from this one. Every public method in that class will be callable
+ * through Piwik's API.
+ * 
+ * ### Example
+ * 
+ *     class MyAPI extends API
+ *     {
+ *         public function myMethod($idSite, $period, $date, $segment = false)
+ *         {
+ *             $dataTable = // ... get some data ...
+ *             return $dataTable;
+ *         }
+ *     }
+ * 
+ * @api
+ */
 abstract class API extends Singleton
 {
 
-}
+}
\ No newline at end of file