diff --git a/core/API/Request.php b/core/API/Request.php
index 76ee0791bea62946de6c73fa38e8fd83049f27c0..4edc8214654e6ee08761725880b8b5ca3d9a9854 100644
--- a/core/API/Request.php
+++ b/core/API/Request.php
@@ -25,14 +25,24 @@ use Piwik\UrlHelper;
*
* The Request class is used throughout Piwik to call API methods. The difference
* between using Request and calling API methods directly is that Request
- * will do more after calling the API including: apply generic filters, apply queued filters,
- * and handle the **flat** and **label** query parameters.
+ * will do more after calling the API including: applying generic filters, applying queued filters,
+ * and handling the **flat** and **label** query parameters.
*
* Additionally, the Request class will **forward current query parameters** to the request
* which is more convenient than calling {@link Piwik\Common::getRequestVar()} many times over.
*
- * In most cases, using a Request object to query the API is the right way to go.
+ * In most cases, using a Request object to query the API is the correct approach.
*
+ * ### Post-processing
+ *
+ * The return value of API methods undergo some extra processing before being returned by Request.
+ * To learn more about what happens to API results, read [this](/guides/piwiks-web-api#extra-report-processing).
+ *
+ * ### Output Formats
+ *
+ * The value returned by Request will be serialized to a certain format before being returned.
+ * To see the list of supported output formats, read [this](/guides/piwiks-web-api#output-formats).
+ *
* ### Examples
*
* **Basic Usage**
@@ -44,14 +54,15 @@ use Piwik\UrlHelper;
*
* **Getting a unrendered DataTable**
*
- * // use convenience the convenience method 'processRequest'
+ * // use the convenience method 'processRequest'
* $dataTable = Request::processRequest('UserSettings.getWideScreen', array(
* 'idSite' => 1,
* 'date' => 'yesterday',
* 'period' => 'week',
- * 'format' => 'original', // this is the important bit
* 'filter_limit' => 5,
* 'filter_offset' => 0
+ *
+ * 'format' => 'original', // this is the important bit
* ));
* echo "This DataTable has " . $dataTable->getRowsCount() . " rows.";
*
@@ -112,10 +123,10 @@ class Request
/**
* Constructor.
*
- * @param string $request GET request that defines the API call (must at least contain a **method** parameter),
- * eg, `'method=UserSettings.getWideScreen&idSite=1&date=yesterday&period=week&format=xml'`
- * If a request is not provided, then we use the $_GET and $_POST superglobal and fetch
- * the values directly from the HTTP GET query.
+ * @param string|array $request Query string that defines the API call (must at least contain a **method** parameter),
+ * eg, `'method=UserSettings.getWideScreen&idSite=1&date=yesterday&period=week&format=xml'`
+ * If a request is not provided, then we use the values in the `$_GET` and `$_POST`
+ * superglobals.
*/
public function __construct($request = null)
{
@@ -169,8 +180,12 @@ class Request
* - running generic filters unless **disable_generic_filters** is set to 1
* - URL decoding label column values
* - running queued filters unless **disable_queued_filters** is set to 1
- * - removes columns based on the values of the **hideColumns** and **showColumns** query parameters
- * - filters rows if the **label** query parameter is set
+ * - removing columns based on the values of the **hideColumns** and **showColumns** query parameters
+ * - filtering rows if the **label** query parameter is set
+ * - converting the result to the appropriate format (ie, XML, JSON, etc.)
+ *
+ * If `'original'` is supplied for the output format, the result is returned as a PHP
+ * object.
*
* @throws PluginDeactivatedException if the module plugin is not activated.
* @throws Exception if the requested API method cannot be called, if required parameters for the
@@ -212,10 +227,10 @@ class Request
}
/**
- * Returns the class name of a plugin's API given the plugin name.
+ * Returns the name of a plugin's API class by plugin name.
*
- * @param string $plugin The plugin name.
- * @return string
+ * @param string $plugin The plugin name, eg, `'Referrers'`.
+ * @return string The fully qualified API class name, eg, `'\Piwik\Plugins\Referrers\API'`.
*/
static public function getClassNameAPI($plugin)
{
@@ -254,7 +269,7 @@ class Request
}
/**
- * Returns array( $class, $method) from the given string $class.$method
+ * Returns array($class, $method) from the given string $class.$method
*
* @param string $parameter
* @throws Exception
@@ -273,10 +288,10 @@ class Request
* Helper method that processes an API request in one line using the variables in `$_GET`
* and `$_POST`.
*
- * @param string $method The API method to call, ie, Actions.getPageTitles
+ * @param string $method The API method to call, ie, `'Actions.getPageTitles'`.
* @param array $paramOverride The parameter name-value pairs to use instead of what's
- * in $_GET & $_POST.
- * @return mixed The result of the API request.
+ * in `$_GET` & `$_POST`.
+ * @return mixed The result of the API request. See {@link process()}.
*/
public static function processRequest($method, $paramOverride = array())
{
@@ -293,7 +308,7 @@ class Request
/**
* Returns the original request parameters in the current query string as an array mapping
- * query parameter names with values. This result of this function will not be affected
+ * query parameter names with values. The result of this function will not be affected
* by any modifications to `$_GET` and will not include parameters in `$_POST`.
*
* @return array
@@ -308,7 +323,7 @@ class Request
}
/**
- * Returns URL for the current requested report w/o any filter parameters.
+ * Returns the URL for the current requested report w/o any filter parameters.
*
* @param string $module The API module.
* @param string $action The API action.
@@ -360,7 +375,7 @@ class Request
}
/**
- * Returns the unmodified segment from the original request.
+ * Returns the segment query parameter from the original request, without modifications.
*
* @return array|bool
*/
diff --git a/core/ArchiveProcessor.php b/core/ArchiveProcessor.php
index 435fb69ad940bc312418ded58f4f9927150d8513..6aa62cdc9d2b9e9b25be6676f601c97819fbb1df 100644
--- a/core/ArchiveProcessor.php
+++ b/core/ArchiveProcessor.php
@@ -22,24 +22,7 @@ use Piwik\Db;
use Piwik\Period;
/**
- * Used to insert numeric and blob archive data, and to aggregate archive data.
- *
- * During the Archiving process an instance of this class is used by plugins
- * to cache aggregated analytics statistics.
- *
- * When the {@link Archive} class is used to query for archive data and that archive
- * data is found to be absent, the archiving process is launched. Instances of the
- * {@link Piwik\Plugin\Archiver} classes for every plugin that supplies one are
- * then used to execute archiving logic.
- *
- * Plugins access ArchiveProcessor instances through the {@link Piwik\Plugin\Archiver} class.
- * Read the docs for {@link Piwik\Plugin\Archiver} to learn more about the process.
- *
- * ### Limitations
- *
- * - It is currently only possible to aggregate statistics for one site and period
- * at a time. The archive.php cron script does, however, issue asynchronous HTTP
- * requests that initiate archiving, so statistics can be calculated in parallel.
+ * Used by {@link Piwik\Plugin\Archiver} instances to insert and aggregate archive data.
*
* ### See also
*
@@ -52,7 +35,7 @@ use Piwik\Period;
*
* **Inserting numeric data**
*
- * // function in an Archiver descendent
+ * // function in an Archiver descendant
* public function aggregateDayReport()
* {
* $archiveProcessor = $this->getProcessor();
@@ -63,7 +46,7 @@ use Piwik\Period;
*
* **Inserting serialized DataTables**
*
- * // function in an Archiver descendent
+ * // function in an Archiver descendant
* public function aggregateDayReport()
* {
* $archiveProcessor = $this->getProcessor();
@@ -79,7 +62,7 @@ use Piwik\Period;
*
* **Aggregating archive data**
*
- * // function in Archiver descendent
+ * // function in Archiver descendant
* public function aggregateMultipleReports()
* {
* $archiveProcessor = $this->getProcessor();
@@ -147,7 +130,8 @@ class ArchiveProcessor
}
/**
- * Returns the Parameters object containing the site, period and segment used with this archive.
+ * Returns the {@link Parameters} object containing the site, period and segment we're archiving
+ * data for.
*
* @return Parameters
* @api
@@ -188,20 +172,19 @@ class ArchiveProcessor
* @param int $maximumRowsInDataTableLevelZero Maximum number of rows allowed in the top level DataTable.
* @param int $maximumRowsInSubDataTable Maximum number of rows allowed in each subtable.
* @param string $columnToSortByBeforeTruncation The name of the column to sort by before truncating a DataTable.
- * @param array $columnsAggregationOperation Operations for aggregating columns, @see Row::sumRow().
- * @param array $columnsToRenameAfterAggregation For columns that must change names when summed because they
- * cannot be summed, eg,
- * `array('nb_uniq_visitors' => 'sum_daily_nb_uniq_visitors')`.
+ * @param array $columnsAggregationOperation Operations for aggregating columns, see {@link Row::sumRow()}.
+ * @param array $columnsToRenameAfterAggregation Columns mapped to new names for columns that must change names
+ * when summed because they cannot be summed, eg,
+ * `array('nb_uniq_visitors' => 'sum_daily_nb_uniq_visitors')`.
* @return array Returns the row counts of each aggregated report before truncation, eg,
- * ```
- * array(
- * 'report1' => array('level0' => $report1->getRowsCount,
- * 'recursive' => $report1->getRowsCountRecursive()),
- * 'report2' => array('level0' => $report2->getRowsCount,
- * 'recursive' => $report2->getRowsCountRecursive()),
- * ...
- * )
- * ```
+ *
+ * array(
+ * 'report1' => array('level0' => $report1->getRowsCount,
+ * 'recursive' => $report1->getRowsCountRecursive()),
+ * 'report2' => array('level0' => $report2->getRowsCount,
+ * 'recursive' => $report2->getRowsCountRecursive()),
+ * ...
+ * )
* @api
*/
public function aggregateDataTableRecords($recordNames,
@@ -241,12 +224,12 @@ class ArchiveProcessor
* @return array|int Returns the array of aggregate values. If only one metric was aggregated,
* the aggregate value will be returned as is, not in an array.
* For example, if `array('nb_visits', 'nb_hits')` is supplied for `$columns`,
- * ```
- * array(
- * 'nb_visits' => 3040,
- * 'nb_hits' => 405
- * )
- * ```
+ *
+ * array(
+ * 'nb_visits' => 3040,
+ * 'nb_hits' => 405
+ * )
+ *
* could be returned. If `array('nb_visits')` or `'nb_visits'` is used for `$columns`,
* then `3040` would be returned.
* @api
@@ -286,9 +269,8 @@ class ArchiveProcessor
*
* @param array $numericRecords A name-value mapping of numeric values that should be
* archived, eg,
- * ```
- * array('Referrers_distinctKeywords' => 23, 'Referrers_distinctCampaigns' => 234)
- * ```
+ *
+ * array('Referrers_distinctKeywords' => 23, 'Referrers_distinctCampaigns' => 234)
* @api
*/
public function insertNumericRecords($numericRecords)
@@ -302,7 +284,7 @@ class ArchiveProcessor
* Caches a single numeric record in the archive for this processor's site, period and
* segment.
*
- * Numeric values are not inserted if they equal 0.
+ * Numeric values are not inserted if they equal `0`.
*
* @param string $name The name of the numeric value, eg, `'Referrers_distinctKeywords'`.
* @param float $value The numeric value.
diff --git a/core/ArchiveProcessor/Parameters.php b/core/ArchiveProcessor/Parameters.php
index 7ac9129b3b458db17cca6c4f624eb3abeb6e3dbd..25db149f2f4ac8c23a9ae21621d3f4e1c3426bab 100644
--- a/core/ArchiveProcessor/Parameters.php
+++ b/core/ArchiveProcessor/Parameters.php
@@ -19,9 +19,9 @@ use Piwik\Segment;
use Piwik\Site;
/**
- * An ArchiveProcessor processes data for an Archive determined by these Parameters: website, period and segment.
- *
- * @api
+ * Contains the analytics parameters for the reports that are currently being archived. The analytics
+ * parameters include the **website** the reports describe, the **period** of time the reports describe
+ * and the **segment** used to limit the visit set.
*/
class Parameters
{
@@ -45,6 +45,11 @@ class Parameters
*/
private $requestedPlugin = false;
+ /**
+ * Constructor.
+ *
+ * @ignore
+ */
public function __construct(Site $site, Period $period, Segment $segment)
{
$this->site = $site;
@@ -69,7 +74,7 @@ class Parameters
}
/**
- * Returns the period we computing statistics for.
+ * Returns the period we are computing statistics for.
*
* @return Period
* @api
@@ -83,6 +88,7 @@ class Parameters
* Returns the array of Period which make up this archive.
*
* @return \Piwik\Period[]
+ * @ignore
*/
public function getSubPeriods()
{
@@ -94,6 +100,7 @@ class Parameters
/**
* @return array
+ * @ignore
*/
public function getIdSites()
{
@@ -129,7 +136,7 @@ class Parameters
}
/**
- * Returns the Date end of this period.
+ * Returns the end day of the period in the site's timezone.
*
* @return Date
*/
@@ -139,7 +146,7 @@ class Parameters
}
/**
- * Returns the Date start of this period.
+ * Returns the start day of the period in the site's timezone.
*
* @return Date
*/
@@ -180,5 +187,4 @@ class Parameters
$this->getDateEnd()->getDateEndUTC()
);
}
-
}
\ No newline at end of file
diff --git a/core/Common.php b/core/Common.php
index a65559943441569c96814e6be08a03b2369a157e..26dec8e25e097e28dd127aef838fd4ee5a52706d 100644
--- a/core/Common.php
+++ b/core/Common.php
@@ -18,7 +18,7 @@ use Piwik\Tracker\Cache;
/**
* Contains helper methods used by both Piwik Core and the Piwik Tracking engine.
*
- * This is the only external class loaded by the /piwik.php file.
+ * This is the only non-Tracker class loaded by the **\/piwik.php** file.
*
* @package Piwik
*/
@@ -201,24 +201,24 @@ class Common
* This function is automatically called when {@link getRequestVar()} is called,
* so you should not normally have to use it.
*
- * You should used it when outputting data that isn't escaped and was
+ * This function should be used when outputting data that isn't escaped and was
* obtained from the user (for example when using the `|raw` twig filter on goal names).
*
- * NOTE: Sanitized input should not be used directly in an SQL query; SQL placeholders
- * should still be used.
+ * _NOTE: Sanitized input should not be used directly in an SQL query; SQL placeholders
+ * should still be used._
*
* **Implementation Details**
*
- * - `htmlspecialchars` is used to escape text.
- * - Single quotes are not escaped so "Piwik's amazing community" will still be
- * "Piwik's amazing community".
+ * - [htmlspecialchars](http://php.net/manual/en/function.htmlspecialchars.php) is used to escape text.
+ * - Single quotes are not escaped so **Piwik's amazing community** will still be
+ * **Piwik's amazing community**.
* - Use of the `magic_quotes` setting will not break this method.
- * - Boolean, numeric and null values are simply returned.
+ * - Boolean, numeric and null values are not modified.
*
- * @param mixed $value The variable to be cleaned. If an array is supplied, the contents
+ * @param mixed $value The variable to be sanitized. If an array is supplied, the contents
* of the array will be sanitized recursively. The keys of the array
* will also be sanitized.
- * @param bool $alreadyStripslashed
+ * @param bool $alreadyStripslashed Implementation detail, ignore.
* @throws Exception If `$value` is of an incorrect type.
* @return mixed The sanitized value.
* @api
@@ -299,10 +299,10 @@ class Common
* the user.
*
* Some data in Piwik is stored sanitized (such as site name). In this case you may
- * have to use this method to unsanitize it after it is retrieved.
+ * have to use this method to unsanitize it in order to, for example, output it in JSON.
*
- * @param string|array $value The data to unsanitize. If an array is passed the
- * array is sanitized recursively. Keys are not unsanitized.
+ * @param string|array $value The data to unsanitize. If an array is passed, the
+ * array is sanitized recursively. Key values are not unsanitized.
* @return string|array The unsanitized data.
* @api
*/
@@ -349,18 +349,19 @@ class Common
*
* Use this function to get request parameter values. **_NEVER use `$_GET` and `$_POST` directly._**
*
- * If the variable doesn't have neither a value nor a default value provided, an exception is raised.
+ * If the variable cannot be found, and a default value was not provided, an exception is raised.
*
- * @see sanitizeInputValues() for the applied sanitization
+ * _See {@link sanitizeInputValues()} to learn more about sanitization._
*
- * @param string $varName Name of the request parameter to get. We look in `$_GET[$varName]` and `$_POST[$varName]`
- * for the value.
- * @param string|null $varDefault The value to return if the request parameter doesn't exist or has an empty value.
- * @param string|null $varType Expected type, the value must be one of the following: `'array'`, `'int'`, `'integer'`,
- * `'string'`, `'json'`. If `'json'`, the string value will be `json_decode`-d and all of
- * entries sanitized.
- * @param array|null $requestArrayToUse The array to use instead of $_GET and $_POST.
- * @throws Exception If the request parameter doesn't exist and there is no default value or if the request parameter
+ * @param string $varName Name of the request parameter to get. By default, we look in `$_GET[$varName]`
+ * and `$_POST[$varName]` for the value.
+ * @param string|null $varDefault The value to return if the request parameter cannot be found or has an empty value.
+ * @param string|null $varType Expected type of the request variable. This parameters value must be one of the following:
+ * `'array'`, `'int'`, `'integer'`, `'string'`, `'json'`.
+ *
+ * If `'json'`, the string value will be `json_decode`-d and then sanitized.
+ * @param array|null $requestArrayToUse The array to use instead of `$_GET` and `$_POST`.
+ * @throws Exception If the request parameter doesn't exist and there is no default value, or if the request parameter
* exists but has an incorrect type.
* @return mixed The sanitized request parameter.
* @api
@@ -687,10 +688,10 @@ class Common
/**
* Returns the list of valid language codes.
*
- * @see core/DataFiles/Languages.php
+ * See [core/DataFiles/Languages.php](https://github.com/piwik/piwik/blob/master/core/DataFiles/Languages.php).
*
- * @return array Array of two letter ISO codes mapped with language name (in English). E.g.
- * `array('en' => 'English')`.
+ * @return array Array of two letter ISO codes mapped with their associated language names (in English). E.g.
+ * `array('en' => 'English', 'ja' => 'Japanese')`.
* @api
*/
public static function getLanguagesList()
@@ -702,12 +703,12 @@ class Common
}
/**
- * Returns list of language to country mappings.
+ * Returns a list of language to country mappings.
*
- * @see core/DataFiles/LanguageToCountry.php
+ * See [core/DataFiles/LanguageToCountry.php](https://github.com/piwik/piwik/blob/master/core/DataFiles/LanguageToCountry.php).
*
* @return array Array of two letter ISO language codes mapped with two letter ISO country codes:
- * `array('fr' => 'fr'), // French => France`
+ * `array('fr' => 'fr') // French => France`
* @api
*/
public static function getLanguageToCountryList()
@@ -947,11 +948,13 @@ class Common
*/
/**
- * Returns a string with a comma separated list of placeholders for use in an SQL query based
- * on the list of fields we're referencing. Used mainly to fill the `IN (...)` part of a query.
+ * Returns a string with a comma separated list of placeholders for use in an SQL query. Used mainly
+ * to fill the `IN (...)` part of a query.
*
* @param array|string $fields The names of the mysql table fields to bind, e.g.
* `array(fieldName1, fieldName2, fieldName3)`.
+ *
+ * _Note: The content of the array isn't important, just its length._
* @return string The placeholder string, e.g. `"?, ?, ?"`.
* @api
*/
@@ -995,10 +998,10 @@ class Common
}
/**
- * Mark orphaned object for garbage collection.
+ * Marks an orphaned object for garbage collection.
*
- * For more information: @link http://dev.piwik.org/trac/ticket/374
- * @param $var
+ * For more information: {@link http://dev.piwik.org/trac/ticket/374}
+ * @param $var The object to destroy.
* @api
*/
static public function destroy(&$var)
diff --git a/core/DataAccess/LogAggregator.php b/core/DataAccess/LogAggregator.php
index 43fdb295d55db3e55d576d7604aa14b9d8fa7f07..3f065193b0f37cb36489473b73a0959016363595 100644
--- a/core/DataAccess/LogAggregator.php
+++ b/core/DataAccess/LogAggregator.php
@@ -20,22 +20,20 @@ use Piwik\Metrics;
use Piwik\Tracker\GoalManager;
/**
- * Contains methods that aggregates log data (visits, actions, conversions, ecommerce).
+ * Contains methods that calculate metrics by aggregating log data (visits, actions, conversions,
+ * ecommerce items).
*
- * Plugin {@link Piwik\Plugin\Archiver} descendants can use the methods in this class to aggregate data
- * in the log tables without creating their own SQL queries.
+ * You can use the methods in this class within {@link Piwik\Plugin\Archiver Archiver} descendants
+ * to aggregate log data without having to write SQL queries.
*
- * ### Aggregation Principles
+ * ### Aggregation Dimension
*
- * **Dimensions**
+ * All aggregation methods accept a **dimension** parameter. These parameters are important as
+ * they control how rows in a table are aggregated together.
*
- * Every aggregation method aggregates rows in a specific table. The rows that are
- * aggregated together are chosen by **_dimensions_** that you specify.
- *
- * A **_dimension_** is a table column. In aggregation methods, rows that have the same
- * values for the specified dimensions are aggregated together. Using dimensions you
- * can calculate metrics for an entity (visits, actions, etc.) based on the values of one
- * or more of the entity's properties.
+ * A **_dimension_** is just a table column. Rows that have the same values for these columns are
+ * aggregated together. The result of these aggregations is a set of metrics for every recorded value
+ * of a **dimension**.
*
* _Note: A dimension is essentially the same as a **GROUP BY** field._
*
@@ -52,7 +50,7 @@ use Piwik\Tracker\GoalManager;
* $where = 'log_visit.visitor_returning = 1',
*
* // also count visits for each browser language that are not located in the US
- * $additionalSelects = array('sum(case when log_visit.location_country = 'us' then 1 else 0 end) as nonus'),
+ * $additionalSelects = array('sum(case when log_visit.location_country <> 'us' then 1 else 0 end) as nonus'),
*
* // we're only interested in visits, unique visitors & actions, so don't waste time calculating anything else
* $metrics = array(Metrics::INDEX_NB_UNIQ_VISITORS, Metrics::INDEX_NB_VISITS, Metrics::INDEX_NB_ACTIONS),
@@ -142,7 +140,8 @@ class LogAggregator
protected $segment;
/**
- * Constructor
+ * Constructor.
+ *
* @param \Piwik\ArchiveProcessor\Parameters $params
*/
public function __construct(Parameters $params)
@@ -237,7 +236,8 @@ class LogAggregator
}
/**
- * Aggregates visit logs, optionally grouping by some dimension, and returns the aggregated data.
+ * Executes and returns a query aggregating visit logs, optionally grouping by some dimension. Returns
+ * a DB statement that can be used to iterate over the result
*
* **Result Set**
*
@@ -261,25 +261,26 @@ class LogAggregator
*
* _Note: The metrics returned by this query can be customized by the `$metrics` parameter._
*
- * @param array|string $dimensions SELECT fields (or just one field) that will be grouped by,
+ * @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
+ * is supplied, the query will aggregate visits for each referrer/keyword
* combination.
- * @param bool|string $where Additional condition for the WHERE clause. Can be used to filter
+ * @param bool|string $where Additional condition for the `WHERE` clause. Can be used to filter
* the set of visits that are considered for aggregation.
- * @param array $additionalSelects Additional SELECT fields that are not included in the group by
+ * @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 calculate and return. If false, the query will select
* all of them. The following values can be used:
- * - {@link Piwik\Metrics::INDEX_NB_UNIQ_VISITORS}
- * - {@link Piwik\Metrics::INDEX_NB_VISITS}
- * - {@link Piwik\Metrics::INDEX_NB_ACTIONS}
- * - {@link Piwik\Metrics::INDEX_MAX_ACTIONS}
- * - {@link Piwik\Metrics::INDEX_SUM_VISIT_LENGTH}
- * - {@link Piwik\Metrics::INDEX_BOUNCE_COUNT}
- * - {@link Piwik\Metrics::INDEX_NB_VISITS_CONVERTED}
+ *
+ * - {@link Piwik\Metrics::INDEX_NB_UNIQ_VISITORS}
+ * - {@link Piwik\Metrics::INDEX_NB_VISITS}
+ * - {@link Piwik\Metrics::INDEX_NB_ACTIONS}
+ * - {@link Piwik\Metrics::INDEX_MAX_ACTIONS}
+ * - {@link Piwik\Metrics::INDEX_SUM_VISIT_LENGTH}
+ * - {@link Piwik\Metrics::INDEX_BOUNCE_COUNT}
+ * - {@link Piwik\Metrics::INDEX_NB_VISITS_CONVERTED}
* @param bool|\Piwik\RankingQuery $rankingQuery
* A pre-configured ranking query instance that will be used to limit the result.
* If set, the return value is the array returned by {@link Piwik\RankingQuery::execute()}.
@@ -462,34 +463,31 @@ class LogAggregator
}
/**
- * Aggregates ecommerce item data (everything stored in the **log\_conversion\_item** table)
- * and returns a DB statement that can be used to iterate over the aggregated data.
+ * Executes and returns a query aggregating ecommerce item data (everything stored in the
+ * **log\_conversion\_item** table) and returns a DB statement that can be used to iterate over the result
*
* <a name="queryEcommerceItems-result-set"></a>
* **Result Set**
*
- * The following columns are in each row of the result set:
+ * Each row of the result set represents an aggregated group of ecommerce items. The following
+ * columns are in each row of the result set:
*
- * - **{@link Piwik\Metrics::INDEX_ECOMMERCE_ITEM_REVENUE}**: The total revenue for the group of items
- * this row aggregated.
- * - **{@link Piwik\Metrics::INDEX_ECOMMERCE_ITEM_QUANTITY}**: The total number of items of the group
- * this row aggregated.
- * - **{@link Piwik\Metrics::INDEX_ECOMMERCE_ITEM_PRICE}**: The total price for the group of items this
- * row aggregated.
+ * - **{@link Piwik\Metrics::INDEX_ECOMMERCE_ITEM_REVENUE}**: The total revenue for the group of items.
+ * - **{@link Piwik\Metrics::INDEX_ECOMMERCE_ITEM_QUANTITY}**: The total number of items in this group.
+ * - **{@link Piwik\Metrics::INDEX_ECOMMERCE_ITEM_PRICE}**: The total price for the group of items.
* - **{@link Piwik\Metrics::INDEX_ECOMMERCE_ORDERS}**: The total number of orders this group of items
* belongs to. This will be <= to the total number
* of items in this group.
- * - **{@link Piwik\Metrics::INDEX_NB_VISITS}**: The total number of visits during which each item in
- * this group of items was logged.
+ * - **{@link Piwik\Metrics::INDEX_NB_VISITS}**: The total number of visits that caused these items to be logged.
* - **ecommerceType**: Either {@link Piwik\Tracker\GoalManager::IDGOAL_CART} if the items in this group were
* abandoned by a visitor, or {@link Piwik\Tracker\GoalManager::IDGOAL_ORDER} if they
* were ordered by a visitor.
*
* **Limitations**
*
- * Segmentation is not yet supported in this aggregation method.
+ * Segmentation is not yet supported for this aggregation method.
*
- * @param string $dimension One or more **log_conversion_item** column to group aggregated data by.
+ * @param string $dimension One or more **log\_conversion\_item** columns to group aggregated data by.
* Eg, `'idaction_sku'` or `'idaction_sku, idaction_category'`.
* @return Zend_Db_Statement A statement object that can be used to iterate through the query's
* result set. See [above](#queryEcommerceItems-result-set) to learn more
@@ -523,8 +521,8 @@ class LogAggregator
}
/**
- * Aggregates action data (everything in the log_action table) and returns a DB
- * statement that can be used to iterate over the aggregated data.
+ * Executes and returns a query aggregating action data (everything in the log_action table) and returns
+ * a DB statement that can be used to iterate over the result
*
* <a name="queryActionsByDimension-result-set"></a>
* **Result Set**
@@ -539,7 +537,7 @@ class LogAggregator
*
* Additional data can be selected through the `$additionalSelects` parameter.
*
- * _Note: The metrics returned by this query can be customized by the `$metrics` parameter._
+ * _Note: The metrics calculated by this query can be customized by the `$metrics` parameter._
*
* @param array|string $dimensions One or more SELECT fields that will be used to group the log_action
* rows by. This parameter determines which log_action rows will be
@@ -548,8 +546,9 @@ class LogAggregator
* the set of visits that are considered for aggregation.
* @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 calculate and return. If false, the query will select
+ * @param bool|array $metrics The set of metrics to calculate and return. If `false`, the query will select
* all of them. The following values can be used:
+ *
* - {@link Piwik\Metrics::INDEX_NB_UNIQ_VISITORS}
* - {@link Piwik\Metrics::INDEX_NB_VISITS}
* - {@link Piwik\Metrics::INDEX_NB_ACTIONS}
@@ -559,8 +558,10 @@ class LogAggregator
* @param bool|string $joinLogActionOnColumn One or more columns from the **log_link_visit_action** table that
* log_action should be joined on. The table alias used for each join
* is `"log_action$i"` where `$i` is the index of the column in this
- * array. If a string is used for this parameter, the table alias is not
- * suffixed.
+ * array.
+ *
+ * If a string is used for this parameter, the table alias is not
+ * suffixed (since there is only one column).
* @return mixed A Zend_Db_Statement if `$rankingQuery` isn't supplied, otherwise the result of
* {@link Piwik\RankingQuery::execute()}. Read [this](#queryEcommerceItems-result-set)
* to see what aggregate data is calculated by the query.
@@ -627,8 +628,8 @@ class LogAggregator
}
/**
- * Aggregates conversion data (everything in the **log_conversion** table) and returns
- * a DB statement that can be used to iterate over the aggregated data.
+ * Executes a query aggregating conversion data (everything in the **log_conversion** table) and returns
+ * a DB statement that can be used to iterate over the result.
*
* <a name="queryConversionsByDimension-result-set"></a>
* **Result Set**
@@ -645,30 +646,37 @@ class LogAggregator
* - **{@link Piwik\Metrics::INDEX_GOAL_ECOMMERCE_REVENUE_SUBTOTAL}**: The total cost of all ecommerce items sold
* within these conversions. This value does not
* include tax, shipping or any applied discount.
- * _This metric will only be applicable to the special
+ *
+ * _This metric is only applicable to the special
* **ecommerce** goal (where `idGoal == 'ecommerceOrder'`)._
* - **{@link Piwik\Metrics::INDEX_GOAL_ECOMMERCE_REVENUE_TAX}**: The total tax applied to every transaction in these
- * conversions. This metric is only applicable to the special
- * **ecommerce** goal (where `idGoal == 'ecommerceOrder'`).
+ * conversions.
+ *
+ * _This metric is only applicable to the special
+ * **ecommerce** goal (where `idGoal == 'ecommerceOrder'`)._
* - **{@link Piwik\Metrics::INDEX_GOAL_ECOMMERCE_REVENUE_SHIPPING}**: The total shipping cost for every transaction
- * in these conversions. _This metric is only applicable
- * to the special **ecommerce** goal (where
- * `idGoal == 'ecommerceOrder'`)._
+ * in these conversions.
+ *
+ * _This metric is only applicable to the special
+ * **ecommerce** goal (where `idGoal == 'ecommerceOrder'`)._
* - **{@link Piwik\Metrics::INDEX_GOAL_ECOMMERCE_REVENUE_DISCOUNT}**: The total discount applied to every transaction
- * in these conversions. _This metric is only applicable
- * to the special **ecommerce** goal (where
- * `idGoal == 'ecommerceOrder'`)._
+ * in these conversions.
+ *
+ * _This metric is only applicable to the special
+ * **ecommerce** goal (where `idGoal == 'ecommerceOrder'`)._
* - **{@link Piwik\Metrics::INDEX_GOAL_ECOMMERCE_ITEMS}**: The total number of ecommerce items sold in each transaction
- * in these conversions. _This metric is only applicable to the
- * special **ecommerce** goal (where `idGoal =='ecommerceOrder'`).
+ * in these conversions.
+ *
+ * _This metric is only applicable to the special
+ * **ecommerce** goal (where `idGoal == 'ecommerceOrder'`)._
*
* Additional data can be selected through the `$additionalSelects` parameter.
*
* _Note: This method will only query the **log_conversion** table. Other tables cannot be joined
* using this method._
*
- * @param array|string $dimensions One or more SELECT fields that will be used to group the log_conversion
- * rows by. This parameter determines which log_conversion rows will be
+ * @param array|string $dimensions One or more **SELECT** fields that will be used to group the log_conversion
+ * rows by. This parameter determines which **log_conversion** rows will be
* aggregated together.
* @param bool|string $where An optional SQL expression used in the SQL's **WHERE** clause.
* @param array $additionalSelects Additional SELECT fields that are not included in the group by
@@ -692,11 +700,8 @@ class LogAggregator
}
/**
- * Creates and returns an array of SQL SELECT expressions that will count the number
- * of rows for which a specific column falls within specific ranges.
- *
- * The SELECT expressions will count the number of column values that are
- * within each range.
+ * Creates and returns an array of SQL `SELECT` expressions that will each count how
+ * many rows have a column whose value is within a certain range.
*
* **Note:** The result of this function is meant for use in the `$additionalSelects` parameter
* in one of the query... methods (for example {@link queryVisitsByDimension()}).
@@ -722,23 +727,25 @@ class LogAggregator
* LogAggregator::getSelectsFromRangedColumn('visitor_count_visits', $visitCountVisitsRanges, 'log_visit', 'vcv')
* );
*
- * // perform query
+ * // perform the query
* $logAggregator = // get the LogAggregator somehow
* $query = $logAggregator->queryVisitsByDimension($dimensions = array(), $where = false, $selects);
* $tableSummary = $query->fetch();
*
* $numberOfVisitsWithOneAction = $tableSummary['vta0'];
+ * $numberOfVisitsBetweenTwoAnd10 = $tableSummary['vta1'];
+ *
+ * $numberOfVisitsWithVisitCountOfOne = $tableSummary['vcv0'];
*
* @param string $column The name of a column in `$table` that will be summarized.
- * @param array $ranges An array of arrays describing the ranges over which the data in the table
+ * @param array $ranges The array of ranges over which the data in the table
* will be summarized. For example,
* ```
* array(
* array(1, 1),
* array(2, 2),
- * array(3, 5),
- * array(6, 10),
- * array(10) // everything over 10
+ * array(3, 8),
+ * array(8) // everything over 8
* )
* ```
* @param string $table The unprefixed name of the table whose rows will be summarized.
diff --git a/core/DataTable.php b/core/DataTable.php
index ef1d325504a154757b3ddc2a05d0c1072f46753e..f232af65e1b55beb1908c35ccbde44d1c8859111 100644
--- a/core/DataTable.php
+++ b/core/DataTable.php
@@ -45,7 +45,7 @@ require_once PIWIK_INCLUDE_PATH . '/core/Common.php';
* regarding all the data, such as the site or period that the data is for. _Row metadata_
* is information regarding that row, such as a browser logo or website URL.
*
- * Finally, DataTables all contain a special _summary_ row. This row, if it exists, is
+ * Finally, all DataTables contain a special _summary_ row. This row, if it exists, is
* always at the end of the DataTable.
*
* ### Populating DataTables
@@ -68,9 +68,9 @@ require_once PIWIK_INCLUDE_PATH . '/core/Common.php';
* There are two ways to manipulate a DataTable. You can either:
*
* 1. manually iterate through each row and manipulate the data,
- * 2. or you can use predefined Filters.
+ * 2. or you can use predefined filters.
*
- * A Filter is a class that has a 'filter' method which will manipulate a DataTable in
+ * A filter is a class that has a 'filter' method which will manipulate a DataTable in
* some way. There are several predefined Filters that allow you to do common things,
* such as,
*
@@ -80,12 +80,15 @@ require_once PIWIK_INCLUDE_PATH . '/core/Common.php';
* - sort an entire DataTable,
* - and more.
*
- * Using these Filters instead of writing your own code will increase code clarity and
- * reduce code redundancy. Additionally, Filters have the advantage that they can be
- * applied to DataTable\Map instances. So you can visit every DataTable in a DataTable\Map
+ * Using these filters instead of writing your own code will increase code clarity and
+ * reduce code redundancy. Additionally, filters have the advantage that they can be
+ * applied to DataTable\Map instances. So you can visit every DataTable in a {@link DataTable\Map}
* without having to write a recursive visiting function.
*
- * Note: Anonymous functions can be used as DataTable Filters.
+ * All predefined filters exist in the **Piwik\DataTable\Filter** namespace.
+ *
+ * _Note: For convenience, [anonymous functions](http://www.php.net/manual/en/functions.anonymous.php)
+ * can be used as DataTable filters._
*
* ### Applying Filters
*
@@ -97,9 +100,7 @@ require_once PIWIK_INCLUDE_PATH . '/core/Common.php';
*
* ### Learn more
*
- * - **{@link ArchiveProcessor}** — to learn how DataTables are persisted.
- * - **{@link DataTable\Renderer}** — to learn how DataTable data is exported to XML, JSON, etc.
- * - **{@link DataTable\Filter}** — to see all core Filters.
+ * - See **{@link ArchiveProcessor}** to learn how DataTables are persisted.
*
* ### Examples
*
@@ -340,9 +341,9 @@ class DataTable implements DataTableInterface
/**
* Sorts the DataTable rows using the supplied callback function.
*
- * @param string $functionCallback A comparison callback compatible with `usort`.
+ * @param string $functionCallback A comparison callback compatible with {@link usort}.
* @param string $columnSortedBy The column name `$functionCallback` sorts by. This is stored
- * so we can determine how the DataTable is sorted in the future.
+ * so we can determine how the DataTable was sorted in the future.
*/
public function sort($functionCallback, $columnSortedBy)
{
@@ -392,15 +393,15 @@ class DataTable implements DataTableInterface
}
/**
- * Applies filter to this datatable.
+ * Applies a filter to this datatable.
*
* If {@link enableRecursiveFilters()} was called, the filter will be applied
* to all subtables as well.
*
- * @param string|Closure $className Class name, eg. "Sort" or "Sort". If no namespace is supplied,
- * `Piwik\DataTable\Filter` is assumed. This parameter can also be
- * a closure that takes a DataTable as its first parameter.
- * @param array $parameters Array of parameters pass to the filter in addition to the table.
+ * @param string|Closure $className Class name, eg. `"Sort"` or "Piwik\DataTable\Filters\Sort"`. If no
+ * namespace is supplied, `Piwik\DataTable\Filter` is assumed. This parameter
+ * can also be a closure that takes a DataTable as its first parameter.
+ * @param array $parameters Array of extra parameters to pass to the filter.
*/
public function filter($className, $parameters = array())
{
@@ -430,11 +431,11 @@ class DataTable implements DataTableInterface
* Adds a filter and a list of parameters to the list of queued filters. These filters will be
* executed when {@link applyQueuedFilters()} is called.
*
- * Filters that prettify the output or don't need the full set of rows should be queued. This
+ * Filters that prettify the column values or don't need the full set of rows should be queued. This
* way they will be run after the table is truncated which will result in better performance.
*
- * @param string|Closure $className The class name of the filter, eg. Limit
- * @param array $parameters The parameters to give to the filter, eg. array( $offset, $limit) for the filter Limit
+ * @param string|Closure $className The class name of the filter, eg. `'Limit'`.
+ * @param array $parameters The parameters to give to the filter, eg. `array($offset, $limit)` for the Limit filter.
*/
public function queueFilter($className, $parameters = array())
{
@@ -460,7 +461,7 @@ class DataTable implements DataTableInterface
* Sums a DataTable to this one.
*
* This method will sum rows that have the same label. If a row is found in `$tableToSum` whose
- * label is not found in `$this`, the row will be added to `$this` DataTable.
+ * label is not found in `$this`, the row will be added to `$this`.
*
* If the subtables for this table are loaded, they will be summed as well.
*
@@ -493,7 +494,7 @@ class DataTable implements DataTableInterface
* label => row ID mappings.
*
* @param string $label `'label'` column value to look for.
- * @return Row|false The row if found, false if otherwise.
+ * @return Row|false The row if found, `false` if otherwise.
*/
public function getRowFromLabel($label)
{
@@ -650,7 +651,7 @@ class DataTable implements DataTableInterface
/**
* Sets the summary row.
*
- * Note: A dataTable can have only one summary row.
+ * _Note: A DataTable can have only one summary row._
*
* @param Row $row
* @return Row Returns `$row`.
@@ -685,10 +686,10 @@ class DataTable implements DataTableInterface
/**
* Adds a new row from an array.
*
- * You can add Row metadata with this method.
+ * You can add row metadata with this method.
*
- * @param array $row eg. array(Row::COLUMNS => array('visits' => 13, 'test' => 'toto'),
- * Row::METADATA => array('mymetadata' => 'myvalue'))
+ * @param array $row eg. `array(Row::COLUMNS => array('visits' => 13, 'test' => 'toto'),
+ * Row::METADATA => array('mymetadata' => 'myvalue'))`
*/
public function addRowFromArray($row)
{
@@ -700,7 +701,7 @@ class DataTable implements DataTableInterface
*
* Row metadata cannot be added with this method.
*
- * @param array $row eg. array('name' => 'google analytics', 'license' => 'commercial')
+ * @param array $row eg. `array('name' => 'google analytics', 'license' => 'commercial')`
*/
public function addRowFromSimpleArray($row)
{
@@ -757,11 +758,11 @@ class DataTable implements DataTableInterface
}
/**
- * Returns the list of columns the rows in this datatable contain. This will return the
- * columns of the first row with data and assume they occur in every other row as well.
+ * Returns the names of every column this DataTable contains. This method will return the
+ * columns of the first row with data and will assume they occur in every other row as well.
*
- * Note: If column names still use their in-database INDEX values (@see Metrics), they
- * will be converted to their string name in the array result.
+ *_ Note: If column names still use their in-database INDEX values (@see Metrics), they
+ * will be converted to their string name in the array result._
*
* @return array Array of string column names.
*/
@@ -851,8 +852,8 @@ class DataTable implements DataTableInterface
}
/**
- * Returns the number of rows in this DataTable summed with the row count of each subtable
- * in the DataTable hierarchy. This includes the subtables of subtables and further descendants.
+ * Returns the number of rows in the entire DataTable hierarchy. This is the number of rows in this DataTable
+ * summed with the row count of each descendant subtable.
*
* @return int
*/
@@ -998,7 +999,7 @@ class DataTable implements DataTableInterface
/**
* Returns a string representation of this DataTable for convenient viewing.
*
- * Note: This uses the Html DataTable renderer.
+ * _Note: This uses the **html** DataTable renderer._
*
* @return string
*/
@@ -1062,6 +1063,7 @@ class DataTable implements DataTableInterface
* @param int $maximumRowsInSubDataTable If not null, defines the maximum number of rows allowed in serialized subtables.
* @param string $columnToSortByBeforeTruncation The column to sort by before truncating, eg, `Metrics::INDEX_NB_VISITS`.
* @return array The array of serialized DataTables:
+ *
* array(
* // this DataTable (the root)
* 0 => 'eghuighahgaueytae78yaet7yaetae',
@@ -1130,9 +1132,10 @@ class DataTable implements DataTableInterface
*
* See {@link serialize()}.
*
- * @param string $stringSerialized A serialized DataTable string in the format of a string in the
- * array returned by {@link serialize()}. This function will
- * successfully load DataTables serialized by Piwik 1.X.
+ * _Note: This function will successfully load DataTables serialized by Piwik 1.X._
+ *
+ * @param string $stringSerialized A string with the format of a string in the array returned by
+ * {@link serialize()}.
* @throws Exception if `$stringSerialized` is invalid.
*/
public function addRowsFromSerializedArray($stringSerialized)
@@ -1147,11 +1150,12 @@ class DataTable implements DataTableInterface
}
/**
- * Adds many rows from an array.
+ * Adds multiple rows from an array.
*
- * You can add Row metadata with this method.
+ * You can add row metadata with this method.
*
* @param array $array Array with the following structure
+ *
* array(
* // row1
* array(
@@ -1177,16 +1181,17 @@ class DataTable implements DataTableInterface
}
/**
- * Adds many rows from an array containing arrays of column values.
+ * Adds multiple rows from an array containing arrays of column values.
*
* Row metadata cannot be added with this method.
*
- * @param array $array Array with the simple structure:
+ * @param array $array Array with the following structure:
+ *
* array(
* array( col1_name => valueA, col2_name => valueC, ...),
* array( col1_name => valueB, col2_name => valueD, ...),
* )
- * @throws Exception
+ * @throws Exception if `$array` is in an incorrect format.
*/
public function addRowsFromSimpleArray($array)
{
@@ -1257,30 +1262,36 @@ class DataTable implements DataTableInterface
}
/**
- * Rewrites the input $array
- * array (
- * LABEL => array(col1 => X, col2 => Y),
- * LABEL2 => array(col1 => X, col2 => Y),
- * )
- * to a DataTable, ie. with the internal structure
- * array (
- * array( Row::COLUMNS => array('label' => LABEL, col1 => X, col2 => Y)),
- * array( Row::COLUMNS => array('label' => LABEL2, col1 => X, col2 => Y)),
- * )
+ * Rewrites the input `$array`
+ *
+ * array (
+ * LABEL => array(col1 => X, col2 => Y),
+ * LABEL2 => array(col1 => X, col2 => Y),
+ * )
+ *
+ * to a DataTable with rows that look like:
+ *
+ * array (
+ * array( Row::COLUMNS => array('label' => LABEL, col1 => X, col2 => Y)),
+ * array( Row::COLUMNS => array('label' => LABEL2, col1 => X, col2 => Y)),
+ * )
*
- * It also works with array having only one value per row, eg.
- * array (
- * LABEL => X,
- * LABEL2 => Y,
- * )
- * would be converted to:
- * array (
- * array( Row::COLUMNS => array('label' => LABEL, 'value' => X)),
- * array( Row::COLUMNS => array('label' => LABEL2, 'value' => Y)),
- * )
+ * Will also convert arrays like:
+ *
+ * array (
+ * LABEL => X,
+ * LABEL2 => Y,
+ * )
+ *
+ * to:
+ *
+ * array (
+ * array( Row::COLUMNS => array('label' => LABEL, 'value' => X)),
+ * array( Row::COLUMNS => array('label' => LABEL2, 'value' => Y)),
+ * )
*
- * @param array $array Indexed array, two formats are supported
- * @param array|null $subtablePerLabel An indexed array of up to one DataTable to associate as a sub table
+ * @param array $array Indexed array, two formats supported, see above.
+ * @param array|null $subtablePerLabel An array mapping label values with DataTable instances to associate as a subtable.
* @return \Piwik\DataTable
*/
public static function makeFromIndexedArray($array, $subtablePerLabel = null)
@@ -1305,7 +1316,7 @@ class DataTable implements DataTableInterface
/**
* Sets the maximum depth level to at least a certain value. If the current value is
- * greater than the supplied level, the maximum nesting level is not changed.
+ * greater than `$atLeastLevel`, the maximum nesting level is not changed.
*
* The maximum depth level determines the maximum number of subtable levels in the
* DataTable tree. For example, if it is set to `2`, this DataTable is allowed to
@@ -1325,7 +1336,7 @@ class DataTable implements DataTableInterface
* Returns metadata by name.
*
* @param string $name The metadata name.
- * @return mixed|false The metadata value or false if it cannot be found.
+ * @return mixed|false The metadata value or `false` if it cannot be found.
*/
public function getMetadata($name)
{
@@ -1369,7 +1380,7 @@ class DataTable implements DataTableInterface
}
/**
- * Sets metadata erasing existing values.
+ * Sets metadata, erasing existing values.
*
* @param array $values Array mapping metadata names with metadata values.
*/
@@ -1392,12 +1403,12 @@ class DataTable implements DataTableInterface
/**
* Traverses a DataTable tree using an array of labels and returns the row
- * it finds or false if it cannot find one. The number of path segments that
+ * it finds or `false` if it cannot find one. The number of path segments that
* were successfully walked is also returned.
*
- * If $missingRowColumns is supplied, the specified path is created. When
- * a subtable is encountered w/o the queried label, a new row is created
- * with the label, and a subtable is added to the row.
+ * If `$missingRowColumns` is supplied, the specified path is created. When
+ * a subtable is encountered w/o the required label, a new row is created
+ * with the label, and a new subtable is added to the row.
*
* Read [http://en.wikipedia.org/wiki/Tree_(data_structure)#Traversal_methods](http://en.wikipedia.org/wiki/Tree_(data_structure)#Traversal_methods)
* for more information about tree walking.
@@ -1410,9 +1421,9 @@ class DataTable implements DataTableInterface
* created for path labels that cannot be found.
* @param int $maxSubtableRows The maximum number of allowed rows in new subtables. New
* subtables are only created if `$missingRowColumns` is provided.
- * @return array First element is the found row or false. Second element is
+ * @return array First element is the found row or `false`. Second element is
* the number of path segments walked. If a row is found, this
- * will be == to count($path). Otherwise, it will be the index
+ * will be == to `count($path)`. Otherwise, it will be the index
* of the path segment that we could not find.
*/
public function walkPath($path, $missingRowColumns = false, $maxSubtableRows = 0)
@@ -1468,15 +1479,15 @@ class DataTable implements DataTableInterface
}
/**
- * Returns a new DataTable in which the rows of this table are replaced with the aggregatated rows of all its subtable's.
+ * Returns a new DataTable in which the rows of this table are replaced with the aggregatated rows of all its subtables.
*
* @param string|bool $labelColumn If supplied the label of the parent row will be added to
* a new column in each subtable row.
*
- * If set to, 'label' each subtable row's label will be prepended
+ * If set to, `'label'` each subtable row's label will be prepended
* w/ the parent row's label. So `'child_label'` becomes
* `'parent_label - child_label'`.
- * @param bool $useMetadataColumn If true and if $labelColumn is supplied, the parent row's
+ * @param bool $useMetadataColumn If true and if `$labelColumn` is supplied, the parent row's
* label will be added as metadata and not a new column.
* @return \Piwik\DataTable
*/
diff --git a/core/Db.php b/core/Db.php
index a1ae66916dd2681243d8bcc6c847f436ece8bde1..bfd88878d6ba32c39922dc8c92f8042a9cbe1de9 100644
--- a/core/Db.php
+++ b/core/Db.php
@@ -15,20 +15,19 @@ use Piwik\Db\Adapter;
use Piwik\Tracker;
/**
- * Helper class that contains SQL related helper functions.
+ * Contains SQL related helper functions for Piwik's MySQL database.
*
- * Plugins should use this class to execute SQL against the database.
+ * Plugins should always use this class to execute SQL against the database.
*
* ### Examples
*
- * **Basic Usage**
- *
* $rows = Db::fetchAll("SELECT col1, col2 FROM mytable WHERE thing = ?", array('thingvalue'));
* foreach ($rows as $row) {
* doSomething($row['col1'], $row['col2']);
* }
*
* $value = Db::fetchOne("SELECT MAX(col1) FROM mytable");
+ * doSomethingElse($value);
*
* Db::query("DELETE FROM mytable WHERE id < ?", array(23));
*
@@ -58,9 +57,9 @@ class Db
}
/**
- * Create the database object and connects to the database.
+ * Connects to the database.
*
- * Shouldn't be called directly, use {@link get()}.
+ * Shouldn't be called directly, use {@link get()} instead.
*
* @param array|null $dbInfos Connection parameters in an array. Defaults to the `[database]`
* INI config section.
@@ -101,9 +100,10 @@ class Db
}
/**
- * Executes an unprepared SQL query. Recommended for DDL statements like CREATE,
- * DROP and ALTER. The return value is DBMS-specific. For MySQLI, it returns the
- * number of rows affected. For PDO, it returns the `Zend_Db_Statement` object.
+ * Executes an unprepared SQL query. Recommended for DDL statements like `CREATE`,
+ * `DROP` and `ALTER`. The return value is DBMS-specific. For MySQLI, it returns the
+ * number of rows affected. For PDO, it returns a
+ * [Zend_Db_Statement](http://framework.zend.com/manual/1.12/en/zend.db.statement.html) object.
*
* @param string $sql The SQL query.
* @throws \Exception If there is an error in the SQL.
@@ -128,10 +128,11 @@ class Db
}
/**
- * Executes an SQL query and returns the Zend_Db_Statement object.
- * If you want to fetch data from the DB you should use one of the fetch... functions.
- *
- * See also [http://framework.zend.com/manual/en/zend.db.statement.html](http://framework.zend.com/manual/en/zend.db.statement.html).
+ * Executes an SQL query and returns the [Zend_Db_Statement](http://framework.zend.com/manual/1.12/en/zend.db.statement.html)
+ * for the query.
+ *
+ * This method is meant for non-query SQL statements like `INSERT` and `UPDATE. If you want to fetch
+ * data from the DB you should use one of the fetch... functions.
*
* @param string $sql The SQL query.
* @param array $parameters Parameters to bind in the query, eg, `array(param1 => value1, param2 => value2)`.
@@ -149,12 +150,13 @@ class Db
}
/**
- * Executes the SQL query and fetches all the rows from the result set.
+ * Executes an SQL `SELECT` statement and returns all fetched rows from the result set.
*
* @param string $sql The SQL query.
* @param array $parameters Parameters to bind in the query, eg, `array(param1 => value1, param2 => value2)`.
* @throws \Exception If there is a problem with the SQL or bind parameters.
- * @return array (one row in the array per row fetched in the DB)
+ * @return array The fetched rows, each element is an associative array mapping column names
+ * with column values.
*/
static public function fetchAll($sql, $parameters = array())
{
@@ -167,12 +169,13 @@ class Db
}
/**
- * Executes an SQL query and fetches the first row of the result.
+ * Executes an SQL `SELECT` statement and returns the first row of the result set.
*
* @param string $sql The SQL query.
* @param array $parameters Parameters to bind in the query, eg, `array(param1 => value1, param2 => value2)`.
* @throws \Exception If there is a problem with the SQL or bind parameters.
- * @return array
+ * @return array The fetched row, each element is an associative array mapping column names
+ * with column values.
*/
static public function fetchRow($sql, $parameters = array())
{
@@ -185,7 +188,8 @@ class Db
}
/**
- * Executes an SQL query and fetches the first column of the first row of result set.
+ * Executes an SQL `SELECT` statement and returns the first column value of the first
+ * row in the result set.
*
* @param string $sql The SQL query.
* @param array $parameters Parameters to bind in the query, eg, `array(param1 => value1, param2 => value2)`.
@@ -203,7 +207,7 @@ class Db
}
/**
- * Executes an SQL query and returns the entire result set indexed by the first
+ * Executes an SQL `SELECT` statement and returns the entire result set indexed by the first
* selected field.
*
* @param string $sql The SQL query.
@@ -234,14 +238,15 @@ class Db
*
* **Example**
*
+ * // delete all visit rows whose ID is less than a certain value, 100000 rows at a time
* $idVisit = // ...
* Db::deleteAllRows(Common::prefixTable('log_visit'), "WHERE idvisit <= ?", "idvisit ASC", 100000, array($idVisit));
*
* @param string $table The name of the table to delete from. Must be prefixed (see {@link Piwik\Common::prefixTable()}).
* @param string $where The where clause of the query. Must include the WHERE keyword.
* @param $orderBy The column to order by and the order by direction, eg, `idvisit ASC`.
- * @param int $maxRowsPerQuery The maximum number of rows to delete per DELETE query.
- * @param array $parameters Parameters to bind in the query.
+ * @param int $maxRowsPerQuery The maximum number of rows to delete per `DELETE` query.
+ * @param array $parameters Parameters to bind for each query.
* @return int The total number of rows deleted.
*/
static public function deleteAllRows($table, $where, $orderBy, $maxRowsPerQuery = 100000, $parameters = array())
@@ -264,13 +269,13 @@ class Db
}
/**
- * Runs an OPTIMIZE TABLE query on the supplied table or tables. The table names must be prefixed
- * (see {@link Piwik\Common::prefixTable()}).
+ * Runs an `OPTIMIZE TABLE` query on the supplied table or tables.
*
- * Tables will only be optimized if the `[General] enable_sql_optimize_queries` config option is
+ * Tables will only be optimized if the `[General] enable_sql_optimize_queries` INI config option is
* set to **1**.
*
* @param string|array $tables The name of the table to optimize or an array of tables to optimize.
+ * Table names must be prefixed (see {@link Piwik\Common::prefixTable()}).
* @return \Zend_Db_Statement
*/
static public function optimizeTables($tables)
@@ -306,9 +311,10 @@ class Db
}
/**
- * Drops the supplied table or tables. The table names must be prefixed (see {@link Piwik\Common::prefixTable()}).
+ * Drops the supplied table or tables.
*
* @param string|array $tables The name of the table to drop or an array of table names to drop.
+ * Table names must be prefixed (see {@link Piwik\Common::prefixTable()}).
* @return \Zend_Db_Statement
*/
static public function dropTables($tables)
@@ -321,13 +327,15 @@ class Db
}
/**
- * Locks the supplied table or tables. The table names must be prefixed (see {@link Piwik\Common::prefixTable()}).
+ * Locks the supplied table or tables.
*
- * **NOTE:** Piwik does not require the LOCK TABLES privilege to be available. Piwik
- * should still work in case it is not granted.
+ * **NOTE:** Piwik does not require the `LOCK TABLES` privilege to be available. Piwik
+ * should still work if it has not been granted.
*
- * @param string|array $tablesToRead The table or tables to obtain 'read' locks on.
- * @param string|array $tablesToWrite The table or tables to obtain 'write' locks on.
+ * @param string|array $tablesToRead The table or tables to obtain 'read' locks on. Table names must
+ * be prefixed (see {@link Piwik\Common::prefixTable()}).
+ * @param string|array $tablesToWrite The table or tables to obtain 'write' locks on. Table names must
+ * be prefixed (see {@link Piwik\Common::prefixTable()}).
* @return \Zend_Db_Statement
*/
static public function lockTables($tablesToRead, $tablesToWrite = array())
@@ -353,8 +361,8 @@ class Db
/**
* Releases all table locks.
*
- * **NOTE:** Piwik does not require the LOCK TABLES privilege to be available. Piwik
- * should still work in case it is not granted.
+ * **NOTE:** Piwik does not require the `LOCK TABLES` privilege to be available. Piwik
+ * should still work if it has not been granted.
*
* @return \Zend_Db_Statement
*/
@@ -364,16 +372,16 @@ class Db
}
/**
- * Performs a SELECT on a table one chunk at a time and returns the first
+ * Performs a `SELECT` statement on a table one chunk at a time and returns the first
* successfully fetched value.
*
- * In other words, if running a SELECT on one chunk of the table doesn't
- * return a value, we move on to the next chunk and we keep moving until
- * the SELECT returns a value.
+ * This function will execute a query on one set of rows in a table. If nothing
+ * is fetched, it will execute the query on the next set of rows and so on until
+ * the query returns a value.
*
- * This function will break up a SELECT into several smaller SELECTs and
- * should be used when performing a SELECT that can take a long time to finish.
- * Using several smaller SELECTs will ensure that the table will not be locked
+ * This function will break up a `SELECT into several smaller `SELECT`s and
+ * should be used when performing a `SELECT` that can take a long time to finish.
+ * Using several smaller `SELECT`s will ensure that the table will not be locked
* for too long.
*
* **Example**
@@ -391,13 +399,13 @@ class Db
* // since visits
* return Db::segmentedFetchFirst($sql, $maxIdVisit, 0, -self::$selectSegmentSize);
*
- * @param string $sql The SQL to perform. The last two conditions of the WHERE
- * expression must be as follows: 'id >= ? AND id < ?' where
- * 'id' is the int id of the table.
+ * @param string $sql The SQL to perform. The last two conditions of the `WHERE`
+ * expression must be as follows: `'id >= ? AND id < ?'` where
+ * **id** is the int id of the table.
* @param int $first The minimum ID to loop from.
* @param int $last The maximum ID to loop to.
- * @param int $step The maximum number of rows to scan in each smaller SELECT.
- * @param array $params Parameters to bind in the query, `array(param1 => value1, param2 => value2)`
+ * @param int $step The maximum number of rows to scan in one query.
+ * @param array $params Parameters to bind in the query, eg, `array(param1 => value1, param2 => value2)`
*
* @return string
*/
@@ -417,20 +425,23 @@ class Db
}
/**
- * Performs a SELECT on a table one chunk at a time and returns an array
+ * Performs a `SELECT` on a table one chunk at a time and returns an array
* of every fetched value.
*
- * This function will break up a SELECT into several smaller SELECTs and
- * accumulate the result. It should be used when performing a SELECT that can
- * take a long time to finish. Using several smaller SELECTs will ensure that
+ * This function will break up a `SELECT` query into several smaller queries by
+ * using only a limited number of rows at a time. It will accumulate the results
+ * of each smaller query and return the result.
+ *
+ * This function should be used when performing a `SELECT` that can
+ * take a long time to finish. Using several smaller queries will ensure that
* the table will not be locked for too long.
*
- * @param string $sql The SQL to perform. The last two conditions of the WHERE
- * expression must be as follows: 'id >= ? AND id < ?' where
- * 'id' is the int id of the table.
+ * @param string $sql The SQL to perform. The last two conditions of the `WHERE`
+ * expression must be as follows: `'id >= ? AND id < ?'` where
+ * **id** is the int id of the table.
* @param int $first The minimum ID to loop from.
* @param int $last The maximum ID to loop to.
- * @param int $step The maximum number of rows to scan in each smaller SELECT.
+ * @param int $step The maximum number of rows to scan in one query.
* @param array $params Parameters to bind in the query, `array(param1 => value1, param2 => value2)`
* @return array An array of primitive values.
*/
@@ -453,19 +464,22 @@ class Db
* Performs a SELECT on a table one chunk at a time and returns an array
* of every fetched row.
*
- * This function will break up a SELECT into several smaller SELECTs and
- * accumulate the result. It should be used when performing a SELECT that can
- * take a long time to finish. Using several smaller SELECTs will ensure that
+ * This function will break up a `SELECT` query into several smaller queries by
+ * using only a limited number of rows at a time. It will accumulate the results
+ * of each smaller query and return the result.
+ *
+ * This function should be used when performing a `SELECT` that can
+ * take a long time to finish. Using several smaller queries will ensure that
* the table will not be locked for too long.
*
- * @param string $sql The SQL to perform. The last two conditions of the WHERE
- * expression must be as follows: 'id >= ? AND id < ?' where
- * 'id' is the int id of the table.
+ * @param string $sql The SQL to perform. The last two conditions of the `WHERE`
+ * expression must be as follows: `'id >= ? AND id < ?'` where
+ * **id** is the int id of the table.
* @param int $first The minimum ID to loop from.
* @param int $last The maximum ID to loop to.
- * @param int $step The maximum number of rows to scan in each smaller SELECT.
+ * @param int $step The maximum number of rows to scan in one query.
* @param array $params Parameters to bind in the query, array( param1 => value1, param2 => value2)
- * @return array An array of rows that includes the result set of every executed
+ * @return array An array of rows that includes the result set of every smaller
* query.
*/
static public function segmentedFetchAll($sql, $first, $last, $step, $params = array())
@@ -486,14 +500,21 @@ class Db
}
/**
- * Performs a non-SELECT query on a table one chunk at a time.
+ * Performs a `UPDATE` or `DELETE` statement on a table one chunk at a time.
+ *
+ * This function will break up a query into several smaller queries by
+ * using only a limited number of rows at a time.
+ *
+ * This function should be used when executing a non-query statement will
+ * take a long time to finish. Using several smaller queries will ensure that
+ * the table will not be locked for too long.
*
- * @param string $sql The SQL to perform. The last two conditions of the WHERE
- * expression must be as follows: 'id >= ? AND id < ?' where
- * 'id' is the int id of the table.
+ * @param string $sql The SQL to perform. The last two conditions of the `WHERE`
+ * expression must be as follows: `'id >= ? AND id < ?'` where
+ * **id** is the int id of the table.
* @param int $first The minimum ID to loop from.
* @param int $last The maximum ID to loop to.
- * @param int $step The maximum number of rows to scan in each smaller query.
+ * @param int $step The maximum number of rows to scan in one query.
* @param array $params Parameters to bind in the query, `array(param1 => value1, param2 => value2)`
*/
static public function segmentedQuery($sql, $first, $last, $step, $params = array())
@@ -513,7 +534,7 @@ class Db
/**
* Attempts to get a named lock. This function uses a timeout of 1s, but will
- * retry a set number of time.
+ * retry a set number of times.
*
* @param string $lockName The lock name.
* @param int $maxRetries The max number of times to retry.
diff --git a/core/Filesystem.php b/core/Filesystem.php
index 2eb8ff7a783f9976206d9fa82506d66bf60b4884..aea8f5e1c8ec3af3fe1b3d5246c1b81dda5db860 100644
--- a/core/Filesystem.php
+++ b/core/Filesystem.php
@@ -14,7 +14,7 @@ use Exception;
use Piwik\Tracker\Cache;
/**
- * Contains helper functions that involve the filesystem.
+ * Contains helper functions that deal with the filesystem.
*
* @package Piwik
*/
@@ -92,11 +92,11 @@ class Filesystem
/**
* Attempts to create a new directory. All errors are silenced.
*
- * Note: This function does not create directories recursively.
+ * _Note: This function does **not** create directories recursively._
*
* @param string $path The path of the directory to create.
* @param bool $denyAccess Whether to deny browser access to this new folder by
- * creating a .htaccess file.
+ * creating an **.htaccess** file.
* @api
*/
public static function mkdir($path, $denyAccess = true)
@@ -170,11 +170,12 @@ class Filesystem
/**
* Recursively find pathnames that match a pattern.
+ *
* See {@link http://php.net/manual/en/function.glob.php glob} for more info.
*
* @param string $sDir directory The directory to glob in.
* @param string $sPattern pattern The pattern to match paths against.
- * @param int $nFlags `glob()` flags. See {@link http://php.net/manual/en/function.glob.php}.
+ * @param int $nFlags `glob()` . See {@link http://php.net/manual/en/function.glob.php glob()}.
* @return array The list of paths that match the pattern.
* @api
*/
@@ -200,7 +201,7 @@ class Filesystem
* Recursively deletes a directory.
*
* @param string $dir Path of the directory to delete.
- * @param boolean $deleteRootToo Whether to delete `$dir` or just its contents.
+ * @param boolean $deleteRootToo If true, `$dir` is deleted, otherwise just its contents.
* @param \Closure|false $beforeUnlink An optional closure to execute on a file path before unlinking.
* @api
*/
@@ -238,7 +239,7 @@ class Filesystem
* @param bool $excludePhp Whether to avoid copying files if the file is related to PHP
* (includes .php, .tpl, .twig files).
* @throws Exception If the file cannot be copied.
- * @return bool
+ * @return true
* @api
*/
public static function copy($source, $dest, $excludePhp = false)
diff --git a/core/FrontController.php b/core/FrontController.php
index e9fb8f6093be028b638ee7b9f466bdf065e7cd0d..f45028272abd8a8d1017496da42121abd5256d31 100644
--- a/core/FrontController.php
+++ b/core/FrontController.php
@@ -152,7 +152,7 @@ class FrontController extends Singleton
* This event can be used to customize the error that occurs when a user is denied access
* (for example, displaying an error message, redirecting to a page other than login, etc.).
*
- * @param NoAccessException $exception The exception that was caught.
+ * @param \Piwik\NoAccessException $exception The exception that was caught.
*/
Piwik::postEvent('User.isNotAuthorized', array($exception), $pending = true);
} catch (Exception $e) {
diff --git a/core/IP.php b/core/IP.php
index 6e3140fdae19122f86e79220f49298c9a241f5b8..b13c6264b3997e1c39ab265c93955cb3269a5de9 100644
--- a/core/IP.php
+++ b/core/IP.php
@@ -16,11 +16,11 @@ namespace Piwik;
*
* As of Piwik 1.3, IP addresses are stored in the DB has VARBINARY(16),
* and passed around in network address format which has the advantage of
- * being in big-endian byte order, allowing for binary-safe string
+ * being in big-endian byte order. This allows for binary-safe string
* comparison of addresses (of the same length), even on Intel x86.
*
- * As a matter of naming convention, we use $ip for the network address format
- * and $ipString for the presentation format (i.e., human-readable form).
+ * As a matter of naming convention, we use `$ip` for the network address format
+ * and `$ipString` for the presentation format (i.e., human-readable form).
*
* We're not using the network address format (in_addr) for socket functions,
* so we don't have to worry about incompatibility with Windows UNICODE
@@ -126,7 +126,7 @@ class IP
}
/**
- * Convert presentation format IP address to network address format.
+ * Converts an IP address in presentation format to network address format.
*
* @param string $ipString IP address, either IPv4 or IPv6, e.g., `"127.0.0.1"`.
* @return string Binary-safe string, e.g., `"\x7F\x00\x00\x01"`.
@@ -195,7 +195,7 @@ class IP
}
/**
- * Convert IP address (in network address format) to presentation format.
+ * Converts an IP address (in network address format) to presentation format.
* This is a backward compatibility function for code that only expects
* IPv4 addresses (i.e., doesn't support IPv6).
*
@@ -419,7 +419,7 @@ class IP
}
/**
- * Get hostname for a given IP address.
+ * Retirms the hostname for a given IP address.
*
* @param string $ipStr Human-readable IP address.
* @return string The hostname or unmodified $ipStr on failure.
diff --git a/core/Nonce.php b/core/Nonce.php
index c877228a9168c1f52a43aa771ab071390f2375e9..e90c5af37438f4cd0a2c278396248f5247f2ba50 100644
--- a/core/Nonce.php
+++ b/core/Nonce.php
@@ -19,7 +19,7 @@ use Piwik\Session\SessionNamespace;
* part of a robust defense against cross-site request forgery (CSRF/XSRF). This
* class provides static methods that create and manage nonce values.
*
- * Nonces in Piwik are stored as a session variable and have a configurable expiration:
+ * Nonces in Piwik are stored as a session variable and have a configurable expiration.
*
* Learn more about nonces [here](http://en.wikipedia.org/wiki/Cryptographic_nonce).
*
@@ -29,7 +29,7 @@ use Piwik\Session\SessionNamespace;
class Nonce
{
/**
- * Returns the existing nonce. If none exists, a new nonce will be generated.
+ * Returns an existing nonce by ID. If none exists, a new nonce will be generated.
*
* @param string $id Unique id to avoid namespace conflicts, e.g., `'ModuleName.ActionName'`.
* @param int $ttl Optional time-to-live in seconds; default is 5 minutes. (ie, in 5 minutes,
@@ -66,9 +66,9 @@ class Nonce
* The request is valid if the referrer is a local URL (see {@link Url::isLocalUrl()})
* and if the HTTP origin is valid (see {@link getAcceptableOrigins()}).
*
- * @param string $id Unique id
- * @param string $cnonce Nonce sent to client
- * @return bool true if valid; false otherwise
+ * @param string $id The nonce's unique ID. See {@link getNonce()}.
+ * @param string $cnonce Nonce sent from client.
+ * @return bool `true` if valid; `false` otherwise.
*/
static public function verifyNonce($id, $cnonce)
{
@@ -110,7 +110,7 @@ class Nonce
}
/**
- * Returns Origin HTTP header or false if not found.
+ * Returns the **Origin** HTTP header or `false` if not found.
*
* @return string|bool
*/
@@ -123,7 +123,7 @@ class Nonce
}
/**
- * Returns a list acceptable values for the HTTP Origin header.
+ * Returns a list acceptable values for the HTTP **Origin** header.
*
* @return array
*/
diff --git a/core/Notification.php b/core/Notification.php
index 208ee11c6610783d37a3726957b3b9b77a299264..7c9289d609cd38849097ba9b7513e5251d53c4d6 100644
--- a/core/Notification.php
+++ b/core/Notification.php
@@ -17,10 +17,11 @@ namespace Piwik;
* Notifications consist of a message, a context (the message type), a priority
* and a display type.
*
- * A notification's context will affect the way the message looks, but not how it
- * is displayed. A notification's display type will determine how the message is
- * displayed. The priority determines where it is shown in the list of
- * all displayed notifications.
+ * **The context** affects the way the message looks, but not how it is displayed.
+ *
+ * **The display type** determines how the message is displayed.
+ *
+ * **The priority** determines where it is shown in the list of all displayed notifications.
*
* ### Examples
*
@@ -76,7 +77,7 @@ class Notification
const PRIORITY_MAX = 100;
/**
- * If this flag applied, no close icon will be displayed. _Note: persistent notifications always have a close
+ * If this flag is applied, no close icon will be displayed. _Note: persistent notifications always have a close
* icon._
*
* See {@link $flags}.
@@ -149,7 +150,7 @@ class Notification
/**
* If true, the message will not be escaped before being outputted as HTML. If you set this to
- * true, make sure you escape text yourself in order to avoid any possible XSS vulnerabilities.
+ * `true`, make sure you escape text yourself in order to avoid XSS vulnerabilities.
*
* @var bool
*/
diff --git a/core/Option.php b/core/Option.php
index 8c90022f9963937fc845539e8ce4687a93538776..c7908598c13af4ea4cbbffc70aedb80841b49a92 100644
--- a/core/Option.php
+++ b/core/Option.php
@@ -42,7 +42,7 @@ class Option
* Returns the option value for the requested option `$name`.
*
* @param string $name The option name.
- * @return string|bool The value or false, if not found.
+ * @return string|false The value or `false`, if not found.
*/
public static function get($name)
{
@@ -78,7 +78,7 @@ class Option
*
* @param string $namePattern Pattern of key to match. `'%'` characters should be used as wildcards, and literal
* `'_'` characters should be escaped.
- * @param string $value If supplied options will be deleted only if their value matches this value.
+ * @param string $value If supplied, options will be deleted only if their value matches this value.
*/
public static function deleteLike($namePattern, $value = null)
{
diff --git a/core/Period.php b/core/Period.php
index 91a6856c5460ea7fda7cd06fb044c4b702e79a7d..73b647599d32e9437902820c94cbe4e2b80d6266 100644
--- a/core/Period.php
+++ b/core/Period.php
@@ -20,16 +20,15 @@ use Piwik\Period\Year;
/**
* Date range representation.
*
- * Piwik allows users to view aggregated statistics for each day and for date
- * ranges consisting of several days. When requesting data, a _date_ string and
- * a _period_ string must be used to specify the date range to view statistics
- * for. This is the class that Piwik uses to represent and manipulate those
- * date ranges.
+ * Piwik allows users to view aggregated statistics for single days and for date
+ * ranges consisting of several days. When requesting data, a **date** string and
+ * a **period** string must be used to specify the date range that the data regards.
+ * This is the class Piwik uses to represent and manipulate those date ranges.
*
* There are five types of periods in Piwik: day, week, month, year and range,
* where **range** is any date range. The reason the other periods exist instead
- * of just **range** is that Piwik will archive for days, weeks, months and years
- * periodically, while every other date range is archived on-demand.
+ * of just **range** is that Piwik will pre-archive reports for days, weeks, months
+ * and years, while every other date range is archived on-demand.
*
* ### Examples
*
@@ -74,9 +73,9 @@ abstract class Period
}
/**
- * Creates a new Period instance with a period ID and Date instance.
+ * Creates a new Period instance with a period ID and {@link Date} instance.
*
- * Note: This method cannot create Range periods.
+ * _Note: This method cannot create {@link Period\Range} periods._
*
* @param string $strPeriod `"day"`, `"week"`, `"month"`, `"year"`, `"range"`.
* @param Date|string $date A date within the period or the range of dates.
@@ -119,11 +118,20 @@ abstract class Period
}
/**
- * Returns true $dateString and $period correspond to multiple periods.
- *
+ * Returns true if `$dateString` and `$period` represent multiple periods.
+ *
+ * Will return true for date/period combinations where date references multiple
+ * dates and period is not `'range'`. For example, will return true for:
+ *
+ * - **date** = `2012-01-01,2012-02-01` and **period** = `'day'`
+ * - **date** = `2012-01-01,2012-02-01` and **period** = `'week'`
+ * - **date** = `last7` and **period** = `'month'`
+ *
+ * etc.
+ *
* @static
- * @param $dateString The `'date'` query parameter value.
- * @param $period The `'period'` query parameter value.
+ * @param $dateString The **date** query parameter value.
+ * @param $period The **period** query parameter value.
* @return boolean
*/
public static function isMultiplePeriod($dateString, $period)
@@ -135,11 +143,11 @@ abstract class Period
}
/**
- * Creates a period instance using a Site instance and two strings describing
- * the period & date.
+ * Creates a Period instance using a period, date and timezone.
*
- * @param string $timezone
- * @param string $period The period string: day, week, month, year, range
+ * @param string $timezone The timezone of the date. Only used if `$date` is `'now'`, `'today'`,
+ * `'yesterday'` or `'yesterdaySameTime'`.
+ * @param string $period The period string: `"day"`, `"week"`, `"month"`, `"year"`, `"range"`.
* @param string $date The date or date range string. Can be a special value including
* `'now'`, `'today'`, `'yesterday'`, `'yesterdaySameTime'`.
* @return \Piwik\Period
@@ -211,7 +219,7 @@ abstract class Period
/**
* Returns the period ID.
*
- * @return int A integer unique to this type of period.
+ * @return int A unique integer for this type of period.
*/
public function getId()
{
@@ -267,9 +275,10 @@ abstract class Period
/**
* Add a date to the period.
*
- * Protected because it not yet supported to add periods after the initialization
+ * Protected because adding periods after initialization is not supported.
*
* @param \Piwik\Period $period Valid Period object
+ * @ignore
*/
protected function addSubperiod($period)
{
diff --git a/core/Plugin/API.php b/core/Plugin/API.php
index 474b73fa2910164b0f34e3646d7037c9b29cda6b..732f55ac70094613f0d9ce9a08bca0d53a97f125 100644
--- a/core/Plugin/API.php
+++ b/core/Plugin/API.php
@@ -16,9 +16,11 @@ 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.
+ * Plugins that want to expose functionality through the Reporting API should create a class
+ * that extends this one. Every public method in that class that is not annotated with **@ignore**
+ * will be callable through Piwik's Web API.
+ *
+ * _Note: If your plugin calculates and stores reports, they should be made available through the API._
*
* ### Examples
*
diff --git a/core/Plugin/Archiver.php b/core/Plugin/Archiver.php
index e87e709383fc2c2e92e85acc9f005b29dc036d6c..84c9b5526d93841ba16d1ccae197f5c4ec32e10f 100644
--- a/core/Plugin/Archiver.php
+++ b/core/Plugin/Archiver.php
@@ -15,8 +15,16 @@ use Piwik\ArchiveProcessor;
use Piwik\Config as PiwikConfig;
/**
- * The base class that should be extended by plugins that archive their own
- * metrics.
+ * The base class that should be extended by plugins that compute their own
+ * analytics data.
+ *
+ * Descendants should implement the {@link aggregateDayReport()} and {@link aggregateMultipleReports()}
+ * methods.
+ *
+ * Both of these methods should persist analytics data using the {@link \Piwik\ArchiveProcessor}
+ * instance returned by {@link getProcessor()}. The {@link aggregateDayReport()} method should
+ * compute analytics data using the {@link \Piwik\DataAccess\LogAggregator} instance
+ * returned by {@link getLogAggregator()}.
*
* ### Examples
*
@@ -56,13 +64,13 @@ abstract class Archiver
/**
* Constructor.
*
- * @param ArchiveProcessor $aggregator The ArchiveProcessor instance sent to the archiving
- * event observer.
+ * @param ArchiveProcessor $processor The ArchiveProcessor instance to use when persisting archive
+ * data.
*/
- public function __construct(ArchiveProcessor $aggregator)
+ public function __construct(ArchiveProcessor $processor)
{
$this->maximumRows = PiwikConfig::getInstance()->General['datatable_archiving_maximum_rows_standard'];
- $this->processor = $aggregator;
+ $this->processor = $processor;
}
/**
@@ -71,10 +79,10 @@ abstract class Archiver
* Implementations of this method should do more computation intensive activities such
* as aggregating data across log tables. Since this method only deals w/ data logged for a day,
* aggregating individual log table rows isn't a problem. Doing this for any larger period,
- * however, would cause performance issues.
+ * however, would cause performance degradation.
*
- * Aggregate log table rows using a {@link Piwik\DataAccess\LogAggregator} instance. Get a {@link Piwik\DataAccess\LogAggregator} instance
- * using the {@link getLogAggregator()} method.
+ * Aggregate log table rows using a {@link Piwik\DataAccess\LogAggregator} instance. Get a
+ * {@link Piwik\DataAccess\LogAggregator} instance using the {@link getLogAggregator()} method.
*/
abstract public function aggregateDayReport();
@@ -86,15 +94,17 @@ abstract class Archiver
* week than to aggregate each log entry of the week.
*
* Use {@link Piwik\ArchiveProcessor::aggregateNumericMetrics()} and {@link Piwik\ArchiveProcessor::aggregateDataTableRecords()}
- * to aggregate archived reports. Get the {@link Piwik\ArchiveProcessor} instance using the {@link getProcessor()}.
+ * to aggregate archived reports. Get the {@link Piwik\ArchiveProcessor} instance using the {@link getProcessor()}
+ * method.
*/
abstract public function aggregateMultipleReports();
/**
- * Returns an {@link Piwik\ArchiveProcessor} instance that can be used to insert archive data for
- * this period, segment and site.
+ * Returns a {@link Piwik\ArchiveProcessor} instance that can be used to insert archive data for
+ * the period, segment and site we are archiving data for.
*
* @return \Piwik\ArchiveProcessor
+ * @api
*/
protected function getProcessor()
{
@@ -106,6 +116,7 @@ abstract class Archiver
* for this period, segment and site.
*
* @return \Piwik\DataAccess\LogAggregator
+ * @api
*/
protected function getLogAggregator()
{
diff --git a/core/Plugin/ConsoleCommand.php b/core/Plugin/ConsoleCommand.php
index 4c0169ae331d29a3fd5199193e49d3c88afdd55e..54405256a55434f516ff951d250a3ef59a46936f 100644
--- a/core/Plugin/ConsoleCommand.php
+++ b/core/Plugin/ConsoleCommand.php
@@ -23,6 +23,11 @@ use Symfony\Component\Console\Input\InputInterface;
*/
class ConsoleCommand extends SymfonyCommand
{
+ /**
+ * Constructor.
+ *
+ * @param string|null $name The name of the command, eg, `'generate:api'`.
+ */
public function __construct($name = null)
{
if (!Common::isPhpCliMode()) {
diff --git a/core/Plugin/Controller.php b/core/Plugin/Controller.php
index da5c8a8def9f36574620f98ee143422c6b07b887..27fb10fa9eaf2e3bed925782743bb88fdab1ea9e 100644
--- a/core/Plugin/Controller.php
+++ b/core/Plugin/Controller.php
@@ -42,9 +42,10 @@ use Piwik\API\Proxy;
*
* Plugins that wish to add display HTML should create a Controller that either
* extends from this class or from {@link ControllerAdmin}. Every public method in
- * the controller will be exposed as a controller action.
+ * the controller will be exposed as a controller method and can be invoked via
+ * an HTTP request.
*
- * Learn more about Piwik's MVC system [here](#).
+ * Learn more about Piwik's MVC system [here](/guides/mvc-in-piwik).
*
* ### Examples
*
@@ -77,7 +78,7 @@ abstract class Controller
protected $pluginName;
/**
- * The value of the `'date'` query parameter.
+ * The value of the **date** query parameter.
*
* @var string
* @api
@@ -93,7 +94,7 @@ abstract class Controller
protected $date;
/**
- * The value of the `'idSite'` query parameter.
+ * The value of the **idSite** query parameter.
*
* @var int
* @api
@@ -101,7 +102,7 @@ abstract class Controller
protected $idSite;
/**
- * The Site object created with ($idSite)[#idSite].
+ * The Site object created with {@link $idSite}.
*
* @var Site
* @api
@@ -110,6 +111,7 @@ abstract class Controller
/**
* Constructor.
+ *
* @api
*/
public function __construct()
@@ -135,11 +137,11 @@ abstract class Controller
}
/**
- * Helper method that converts "today" or "yesterday" to the specified 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 $timezone default timezone to use
+ * @param string $date `'today'`, `'yesterday'`, `'YYYY-MM-DD'`
+ * @param string $timezone The timezone to use.
* @return Date
* @api
*/
@@ -194,7 +196,6 @@ abstract class Controller
*
* @param ViewInterface $view The view to render.
* @return string|void
- * @api
*/
protected function renderView(ViewInterface $view)
{
@@ -210,6 +211,7 @@ abstract class Controller
* @throws \Exception if `$pluginName` is not an existing plugin or if `$apiAction` is not an
* existing method of the plugin's API.
* @return string|void See `$fetch`.
+ * @api
*/
protected function renderReport($apiAction)
{
@@ -375,12 +377,10 @@ abstract class Controller
/**
* Returns a URL to a sparkline image for a report served by the current plugin.
*
- * The result of this URL should be used with the [sparkline()](#) twig function.
+ * The result of this URL should be used with the [sparkline()](/api-reference/Piwik/View#twig) twig function.
*
* The current site ID and period will be used.
*
- * See {@link Piwik\Visualization\Sparkline} for more information about the Sparkline visualization.
- *
* @param string $action Method name of the controller that serves the report.
* @param array $customParameters The array of query parameter name/value pairs that
* should be set in result URL.
@@ -406,7 +406,7 @@ abstract class Controller
}
/**
- * Sets the first date available in the calendar.
+ * Sets the first date available in the period selector's calendar.
*
* @param Date $minDate The min date.
* @param View $view The view that contains the period selector.
@@ -420,8 +420,8 @@ abstract class Controller
}
/**
- * Sets the last date available in the calendar. Usually this just the "today" date
- * for a site (which can depend on the timezone of a site).
+ * Sets the last date available in the period selector's calendar. Usually this is just the "today" date
+ * for a site (which varies based on the timezone of a site).
*
* @param Date $maxDate The max date.
* @param View $view The view that contains the period selector.
@@ -684,8 +684,7 @@ abstract class Controller
}
/**
- * Helper method used to redirect the current http request to another module/action.
- * If specified, will also change the idSite, date and/or period query parameters.
+ * Helper method used to redirect the current HTTP request to another module/action.
*
* This function will exit immediately after executing.
*
@@ -745,6 +744,8 @@ abstract class Controller
/**
* Returns default site ID that Piwik should load.
+ *
+ * _Note: This value is a Piwik setting set by each user._
*
* @return bool|int
* @api
@@ -775,6 +776,8 @@ abstract class Controller
/**
* Returns default date for Piwik reports.
*
+ * _Note: This value is a Piwik setting set by each user._
+ *
* @return string `'today'`, `'2010-01-01'`, etc.
* @api
*/
@@ -818,12 +821,10 @@ abstract class Controller
}
/**
- * Checks that the token_auth in the URl matches the current logged in user's token_auth.
+ * Checks that the token_auth in the URL matches the currently logged-in user's token_auth.
*
- * This is a protection against CSRF should be used in controller
- * actions that are either invoked via AJAX or redirect to a page
- * within the site. It should be used in all controller actions that modify
- * Piwik or user settings.
+ * This is a protection against CSRF and should be used in all controller
+ * methods that modify Piwik or any user settings.
*
* **The token_auth should never appear in the browser's address bar.**
*
@@ -877,7 +878,7 @@ abstract class Controller
* @param int $currentValue The value to calculate evolution to.
* @param string $pastDate The date of past value.
* @param int $pastValue The value in the past to calculate evolution from.
- * @return string|bool The HTML or false if the evolution is 0 and the current value is 0.
+ * @return string|false The HTML or `false` if the evolution is 0 and the current value is 0.
* @api
*/
protected function getEvolutionHtml($date, $currentValue, $pastDate, $pastValue)
diff --git a/core/Plugin/ControllerAdmin.php b/core/Plugin/ControllerAdmin.php
index ae9ff0d9bb490d9bc0b16d400cd8f10f3f7cdac4..f20ceb1111321e1f9eaf3fd396c6b2d2b50df436 100644
--- a/core/Plugin/ControllerAdmin.php
+++ b/core/Plugin/ControllerAdmin.php
@@ -26,8 +26,6 @@ use Piwik\View;
* See {@link Controller} to learn more about Piwik controllers.
*
* @package Piwik
- *
- * @api
*/
abstract class ControllerAdmin extends Controller
{
@@ -45,6 +43,9 @@ abstract class ControllerAdmin extends Controller
self::setBasicVariablesAdminView($view);
}
+ /**
+ * @ignore
+ */
static public function displayWarningIfConfigFileNotWritable()
{
$isConfigFileWritable = PiwikConfig::getInstance()->isFileWritable();
@@ -61,7 +62,7 @@ abstract class ControllerAdmin extends Controller
}
/**
- * Assigns a set of variables to a view that would be useful to an Admin controller.
+ * Assigns view properties that would be useful to views that render admin pages.
*
* Assigns the following variables:
*
diff --git a/core/Plugin/Manager.php b/core/Plugin/Manager.php
index 47a012a38a19110464a1e9a25d3c68c5366d8206..502f5b0f833d8eb7f6019759e7b4c89941ca5c18 100644
--- a/core/Plugin/Manager.php
+++ b/core/Plugin/Manager.php
@@ -144,7 +144,7 @@ class Manager extends Singleton
}
/**
- * Returns true if a plugin has been activated.
+ * Returns `true` if a plugin has been activated.
*
* @param string $name Name of plugin, eg, `'Actions'`.
* @return bool
@@ -157,7 +157,7 @@ class Manager extends Singleton
}
/**
- * Returns true if plugin is loaded (in memory).
+ * Returns `true` if plugin is loaded (in memory).
*
* @param string $name Name of plugin, eg, `'Acions'`.
* @return bool
@@ -343,8 +343,9 @@ class Manager extends Singleton
}
/**
- * Returns the theme currently enabled.
- * If no theme is enabled, Zeitgeist is returned (default theme)
+ * Returns the currently enabled theme.
+ *
+ * If no theme is enabled, the **Zeitgeist** plugin is returned (this is the base and default theme).
*
* @return Plugin
* @api
@@ -385,8 +386,9 @@ class Manager extends Singleton
/**
* Returns info regarding all plugins. Loads plugins that can be loaded.
*
- * @return array An array that maps plugin names with arrays of plugin info. Plugin
- * info arrays will contain the following entries:
+ * @return array An array that maps plugin names with arrays of plugin information. Plugin
+ * information consists of the following entries:
+ *
* - **activated**: Whether the plugin is activated.
* - **alwaysActivated**: Whether the plugin should always be activated,
* or not.
@@ -443,7 +445,7 @@ class Manager extends Singleton
}
/**
- * Returns true if the plugin is bundled with core or false if it is third party.
+ * Returns `true` if the plugin is bundled with core or `false` if it is third party.
*
* @param string $name The name of the plugin, eg, `'Actions'`.
* @return bool
@@ -481,9 +483,9 @@ class Manager extends Singleton
/**
- * Load the specified plugins
+ * Load the specified plugins.
*
- * @param array $pluginsToLoad Array of plugins to load
+ * @param array $pluginsToLoad Array of plugins to load.
*/
public function loadPlugins(array $pluginsToLoad)
{
@@ -497,7 +499,7 @@ class Manager extends Singleton
}
/**
- * Disable plugin loading
+ * Disable plugin loading.
*/
public function doNotLoadPlugins()
{
@@ -505,7 +507,7 @@ class Manager extends Singleton
}
/**
- * Disable loading of "always activated" plugins
+ * Disable loading of "always activated" plugins.
*/
public function doNotLoadAlwaysActivatedPlugins()
{
@@ -824,7 +826,7 @@ class Manager extends Singleton
}
/**
- * Return list of names of installed plugins.
+ * Return names of all installed plugins.
*
* @return array
* @api
diff --git a/core/Plugin/Settings.php b/core/Plugin/Settings.php
index 2966ae7075a48987d34667b0f83798eb00106c7d..c8521b9acf2b7f5329f6af195923a40c0218d639 100644
--- a/core/Plugin/Settings.php
+++ b/core/Plugin/Settings.php
@@ -16,8 +16,8 @@ use Piwik\Settings\Setting;
use Piwik\Settings\StorageInterface;
/**
- * Base class of all Settings providers. Plugins that define their own settings can extend
- * this class to easily make their settings available to Piwik users.
+ * Base class of all plugin settings providers. Plugins that define their own configuration settings
+ * can extend this class to easily make their settings available to Piwik users.
*
* Descendants of this class should implement the {@link init()} method and call the
* {@link addSetting()} method for each of the plugin's settings.
diff --git a/core/Plugin/ViewDataTable.php b/core/Plugin/ViewDataTable.php
index 2cd67bbd9e0d7b00f7fa6b1b31fb4e6c13948bf2..65c5ab86fcb4d3b9fb7141653e770137c2073fbf 100644
--- a/core/Plugin/ViewDataTable.php
+++ b/core/Plugin/ViewDataTable.php
@@ -25,7 +25,7 @@ use Piwik\ViewDataTable\RequestConfig as VizRequest;
/**
* The base class of all report visualizations.
*
- * ViewDataTable instances load analytics data via Piwik's API and then output some
+ * ViewDataTable instances load analytics data via Piwik's Reporting API and then output some
* type of visualization of that data.
*
* Visualizations can be in any format. HTML-based visualizations should extend
@@ -38,7 +38,7 @@ use Piwik\ViewDataTable\RequestConfig as VizRequest;
* class is used.
*
* The specific subclass to create is determined, first, by the **viewDataTable** query paramater.
- * If this parameter is not set, then the default visualization type for the report that is being
+ * If this parameter is not set, then the default visualization type for the report being
* displayed is used.
*
* ### Configuring ViewDataTables
@@ -51,13 +51,13 @@ use Piwik\ViewDataTable\RequestConfig as VizRequest;
*
* Display properties can be set at any time before rendering.
*
- * **Request parameters**
+ * **Request properties**
*
- * Request parameters are similar to display properties in the way they are set. They are,
+ * Request properties are similar to display properties in the way they are set. They are,
* however, not used to customize ViewDataTable instances, but in the request to Piwik's
* API when loading analytics data.
*
- * Request parameters are set by setting the fields of a {@link Piwik\ViewDataTable\RequestConfig} object stored in
+ * Request properties are set by setting the fields of a {@link Piwik\ViewDataTable\RequestConfig} object stored in
* the {@link $requestConfig} field. They can be set at any time before rendering.
* Setting them after data is loaded will have no effect.
*
@@ -71,7 +71,7 @@ use Piwik\ViewDataTable\RequestConfig as VizRequest;
* in the {@hook ViewDataTable.configure} event.
*
* ViewDataTable instances are configured by setting and modifying display properties and request
- * parameters.
+ * properties.
*
* ### Creating new visualizations
*
@@ -156,11 +156,15 @@ abstract class ViewDataTable implements ViewInterface
protected $dataTable = null;
/**
+ * Contains display properties for this visualization.
+ *
* @var \Piwik\ViewDataTable\Config
*/
public $config;
/**
+ * Contains request properties for this visualization.
+ *
* @var \Piwik\ViewDataTable\RequestConfig
*/
public $requestConfig;
@@ -171,8 +175,9 @@ abstract class ViewDataTable implements ViewInterface
protected $request;
/**
- * Constructor. Initializes the default config, requestConfig and the request itself. After configuring some
- * mandatory properties reports can modify the view by listening to the hook 'ViewDataTable.configure'.
+ * Constructor. Initializes display and request properties to their default values.
+ * Posts the {@hook ViewDataTable.configure} event which plugins can use to configure the
+ * way reports are displayed.
*/
public function __construct($controllerAction, $apiMethodToRequestDataTable)
{
@@ -230,9 +235,13 @@ abstract class ViewDataTable implements ViewInterface
}
/**
- * Returns the default config. Custom viewDataTables can change the default config to their needs by either
- * modifying this config or creating an own Config class that extends the default Config.
+ * Returns the default config instance.
+ *
+ * Visualizations that define their own display properties should override this method and
+ * return an instance of their new {@link Piwik\ViewDataTable\Config} descendant.
*
+ * See the last example {@link ViewDataTable here} for more information.
+ *
* @return \Piwik\ViewDataTable\Config
*/
public static function getDefaultConfig()
@@ -241,9 +250,13 @@ abstract class ViewDataTable implements ViewInterface
}
/**
- * Returns the default request config. Custom viewDataTables can change the default config to their needs by either
- * modifying this config or creating an own RequestConfig class that extends the default RequestConfig.
+ * Returns the default request config instance.
+ *
+ * Visualizations that define their own request properties should override this method and
+ * return an instance of their new {@link Piwik\ViewDataTable\RequestConfig} descendant.
*
+ * See the last example {@link ViewDataTable here} for more information.
+ *
* @return \Piwik\ViewDataTable\RequestConfig
*/
public static function getDefaultRequestConfig()
@@ -265,7 +278,9 @@ abstract class ViewDataTable implements ViewInterface
}
/**
- * Returns the viewDataTable ID for this DataTable visualization. Derived classes should declare a const ID field
+ * Returns the viewDataTable ID for this DataTable visualization.
+ *
+ * Derived classes should not override this method. They should instead declare a const ID field
* with the viewDataTable ID.
*
* @throws \Exception
@@ -284,10 +299,13 @@ abstract class ViewDataTable implements ViewInterface
}
/**
- * Detects whether the viewDataTable or one of its ancestors has the given id.
- *
- * @param string $viewDataTableId
+ * Returns `true` if this instance's or any of its ancestors' viewDataTable IDs equals the supplied ID,
+ * `false` if otherwise.
+ *
+ * Can be used to test whether a ViewDataTable object is an instance of a certain visualization or not,
+ * without having to know where that visualization is.
*
+ * @param string $viewDataTableId The viewDataTable ID to check for, eg, `'table'`.
* @return bool
*/
public function isViewDataTableId($viewDataTableId)
@@ -298,10 +316,10 @@ abstract class ViewDataTable implements ViewInterface
}
/**
- * Returns the DataTable loaded from the API
+ * Returns the DataTable loaded from the API.
*
* @return DataTable
- * @throws \Exception if not yet defined
+ * @throws \Exception if not yet loaded.
*/
public function getDataTable()
{
@@ -314,10 +332,10 @@ abstract class ViewDataTable implements ViewInterface
/**
* To prevent calling an API multiple times, the DataTable can be set directly.
- * It won't be loaded again from the API in this case
+ * It won't be loaded from the API in this case.
*
- * @param $dataTable
- * @return void $dataTable DataTable
+ * @param DataTable $dataTable The DataTable to use.
+ * @return void
*/
public function setDataTable($dataTable)
{
@@ -390,7 +408,8 @@ abstract class ViewDataTable implements ViewInterface
}
/**
- * Determine if the view data table requests a single data table or not.
+ * Returns `true` if this instance will request a single DataTable, `false` if requesting
+ * more than one.
*
* @return bool
*/
@@ -412,11 +431,14 @@ abstract class ViewDataTable implements ViewInterface
}
/**
- * Here you can define whether your visualization can display a specific data table or not. For instance you may
- * only display your visualization in case a single data table is requested. If the method returns true, the footer
- * icon will be displayed.
+ * Returns `true` if this visualization can display some type of data or not.
+ *
+ * New visualization classes should override this method if they can only visualize certain
+ * types of data. The evolution graph visualization, for example, can only visualize
+ * sets of DataTables. If the API method used results in a single DataTable, the evolution
+ * graph footer icon should not be displayed.
*
- * @param ViewDataTable $view
+ * @param ViewDataTable $view Contains the API request being checked.
* @return bool
*/
public static function canDisplayViewDataTable(ViewDataTable $view)
diff --git a/core/Plugin/Visualization.php b/core/Plugin/Visualization.php
index 73982f7c599a88a34f83c555adb0dc781fd5536f..a9df227bd37f812c02b52f2212f6c5ed22c737ea 100644
--- a/core/Plugin/Visualization.php
+++ b/core/Plugin/Visualization.php
@@ -47,9 +47,11 @@ use Piwik\ViewDataTable\Manager as ViewDataTableManager;
* - The report is loaded through Piwik's Reporting API.
* - The display and request properties that require report data in order to determine a default
* value are defaulted. These properties are:
+ *
* - {@link Piwik\ViewDataTable\Config::$columns_to_display}
* - {@link Piwik\ViewDataTable\RequestConfig::$filter_sort_column}
* - {@link Piwik\ViewDataTable\RequestConfig::$filter_sort_order}
+ *
* - Priority filters are applied to the report (see {@link Piwik\ViewDataTable\Config::$filters}).
* - The filters that are applied to every report in the Reporting API (called **generic filters**)
* are applied. (see {@link Piwik\API\Request})
@@ -122,17 +124,22 @@ use Piwik\ViewDataTable\Manager as ViewDataTableManager;
* public function beforeRender()
* {
* $this->config->max_graph_elements = false;
- * $this->config->datatable_js_type = 'TreemapDataTable';
+ * $this->config->datatable_js_type = 'MyVisualization';
* $this->config->show_flatten_table = false;
* $this->config->show_pagination_control = false;
* $this->config->show_offset_information = false;
* }
* }
- *
- * @api
*/
class Visualization extends ViewDataTable
{
+ /**
+ * The Twig template file to use when rendering, eg, `"@MyPlugin/_myVisualization.twig"`.
+ *
+ * Must be defined by classes that extend Visualization.
+ *
+ * @api
+ */
const TEMPLATE_FILE = '';
private $templateVars = array();
@@ -223,11 +230,12 @@ class Visualization extends ViewDataTable
}
/**
- * Assigns a template variable. All assigned variables are available in the twig view template afterwards. You can
- * assign either one variable by setting $vars and $value or an array of key/value pairs.
+ * Assigns a template variable making it available in the Twig template specified by
+ * {@link TEMPLATE_FILE}.
*
- * @param array|string $vars
- * @param mixed $value
+ * @param array|string $vars One or more variable names to set.
+ * @param mixed $value The value to set each variable to.
+ * @api
*/
public function assignTemplateVar($vars, $value = null)
{
@@ -240,6 +248,13 @@ class Visualization extends ViewDataTable
}
}
+ /**
+ * Returns `true` if there is data to display, `false` if otherwise.
+ *
+ * Derived classes should override this method if they change the amount of data that is loaded.
+ *
+ * @api
+ */
protected function isThereDataToDisplay()
{
return true;
@@ -483,39 +498,43 @@ class Visualization extends ViewDataTable
}
/**
- * Hook that is intended to change the request config that is sent to the API.
+ * Hook that is called before loading report data from the API.
+ *
+ * Use this method to change the request parameters that is sent to the API when requesting
+ * data.
*/
public function beforeLoadDataTable()
{
}
/**
- * Hook that is executed before generic filters like "filter_limit" and "filter_offset" are applied
+ * Hook that is executed before generic filters are applied.
+ *
+ * Use this method if you need access to the entire dataset (since generic filters will
+ * limit and truncate reports).
*/
public function beforeGenericFiltersAreAppliedToLoadedDataTable()
{
-
}
/**
- * This hook is executed after generic filters like "filter_limit" and "filter_offset" are applied
+ * Hook that is executed after generic filters are applied.
*/
public function afterGenericFiltersAreAppliedToLoadedDataTable()
{
-
}
/**
- * This hook is executed after the data table is loaded and after all filteres are applied.
- * Format the data that you want to pass to the view here.
+ * Hook that is executed after the report data is loaded and after all filters have been applied.
+ * Use this method to format the report data before the view is rendered.
*/
public function afterAllFiltersAreApplied()
{
}
/**
- * Hook to make sure config properties have a specific value because the default config can be changed by a
- * report or by request ($_GET and $_POST) params.
+ * Hook that is executed directly before rendering. Use this hook to force display properties to
+ * be a certain value, despite changes from plugins and query parameters.
*/
public function beforeRender()
{
diff --git a/core/ScheduledTask.php b/core/ScheduledTask.php
index 705e606c76e8a8cc7cda80bf463c88b840160c1f..7fedcfd7472442fe14093cdad1a8f827bfacd6ad 100644
--- a/core/ScheduledTask.php
+++ b/core/ScheduledTask.php
@@ -15,7 +15,7 @@ use Exception;
use Piwik\ScheduledTime;
/**
- * Contains metadata describing a chunk of PHP code that should be executed at regular
+ * Contains metadata referencing PHP code that should be executed at regular
* intervals.
*
* See the {@link TaskScheduler} docs to learn more about scheduled tasks.
@@ -72,10 +72,9 @@ class ScheduledTask
/**
* Constructor.
*
- * @param mixed $objectInstance The object or class name for the class that contains the method to
- * regularly execute. Usually this will be a {@link Plugin} instance.
- * @param string $methodName The name of the method of `$objectInstance` that will be regularly
- * executed.
+ * @param mixed $objectInstance The object or class that contains the method to execute regularly.
+ * Usually this will be a {@link Plugin} instance.
+ * @param string $methodName The name of the method that will be regularly executed.
* @param mixed|null $methodParameter An optional parameter to pass to the method when executed.
* Must be convertible to string.
* @param ScheduledTime|null $scheduledTime A {@link ScheduledTime} instance that describes when the method
@@ -111,7 +110,7 @@ class ScheduledTask
}
/**
- * Returns the object instance on which the method should be executed. Returns a class
+ * Returns the object instance that contains the method to execute. Returns a class
* name if the method is static.
*
* @return mixed
@@ -122,7 +121,7 @@ class ScheduledTask
}
/**
- * Returns the class name that contains the method to execute regularly.
+ * Returns the name of the class that contains the method to execute.
*
* @return string
*/
@@ -132,7 +131,7 @@ class ScheduledTask
}
/**
- * Returns the method name that will be regularly executed.
+ * Returns the name of the method that will be executed.
*
* @return string
*/
@@ -142,7 +141,7 @@ class ScheduledTask
}
/**
- * Returns the a value that will be passed to the method when executed, or `null` if
+ * Returns the value that will be passed to the method when executed, or `null` if
* no value will be supplied.
*
* @return string|null
@@ -186,9 +185,9 @@ class ScheduledTask
/**
* Returns a unique name for this scheduled task. The name is stored in the DB and is used
- * to store when tasks were last executed. The name is created using:
+ * to store a task's previous execution time. The name is created using:
*
- * - the class name that contains the method to execute,
+ * - the name of the class that contains the method to execute,
* - the name of the method to regularly execute,
* - and the value that is passed to the executed task.
*
diff --git a/core/Settings/Setting.php b/core/Settings/Setting.php
index ba58abbc3442b27fbedf39c0c79e160107a6e787..670ba37c88ecc024e7e5479d8c6b0617cf95277f 100644
--- a/core/Settings/Setting.php
+++ b/core/Settings/Setting.php
@@ -31,9 +31,9 @@ abstract class Setting
public $type = null;
/**
- * Describes how the setting should be manipulated through Piwik's UI.
+ * Describes what HTML element should be used to manipulate the setting through Piwik's UI.
*
- * See {@link Piwik\Plugin\Settings} for a list of supportted control types.
+ * See {@link Piwik\Plugin\Settings} for a list of supported control types.
*
* @var string
*/
@@ -73,7 +73,7 @@ abstract class Setting
public $introduction = null;
/**
- * Text that will be appear directly underneath the setting title in the _Plugin Settings_ admin
+ * Text that will appear directly underneath the setting title in the _Plugin Settings_ admin
* page. If set, should be a short description of the setting.
*
* @var null|string
@@ -98,13 +98,11 @@ abstract class Setting
*
* **Example**
*
- * ```
- * $setting->validate = function ($value, Setting $setting) {
- * if ($value > 60) {
- * throw new \Exception('The time limit is not allowed to be greater than 60 minutes.');
+ * $setting->validate = function ($value, Setting $setting) {
+ * if ($value > 60) {
+ * throw new \Exception('The time limit is not allowed to be greater than 60 minutes.');
+ * }
* }
- * }
- * ```
*
* @var null|\Closure
*/
@@ -120,15 +118,13 @@ abstract class Setting
*
* **Example**
*
- * ```
- * $setting->transform = function ($value, Setting $setting) {
- * if ($value > 30) {
- * $value = 30;
- * }
+ * $setting->transform = function ($value, Setting $setting) {
+ * if ($value > 30) {
+ * $value = 30;
+ * }
*
- * return (int) $value;
- * }
- * ```
+ * return (int) $value;
+ * }
*
* @var null|\Closure
*/
@@ -185,7 +181,7 @@ abstract class Setting
}
/**
- * Returns true if this setting can be displayed for the current user, false if otherwise.
+ * Returns `true` if this setting can be displayed for the current user, `false` if otherwise.
*
* @return bool
*/
diff --git a/core/Settings/SystemSetting.php b/core/Settings/SystemSetting.php
index e96f1a1fb0cf2ae5d61936f90b2c79ffa9251f62..50e79e11c626845e3b74cec8fe60e843c72ee87f 100644
--- a/core/Settings/SystemSetting.php
+++ b/core/Settings/SystemSetting.php
@@ -16,6 +16,8 @@ use Piwik\Piwik;
/**
* Describes a system wide setting. Only the super user can change this type of setting and
* the value of this setting will affect all users.
+ *
+ * See {@link \Piwik\Plugin\Settings}.
*
* @package Piwik
* @subpackage Settings
@@ -38,7 +40,7 @@ class SystemSetting extends Setting
}
/**
- * Returns the display order. User settings are displayed after system settings.
+ * Returns the display order. System settings are displayed before user settings.
*
* @return int
*/
diff --git a/core/Settings/UserSetting.php b/core/Settings/UserSetting.php
index 7512f693c4231302cf8c830e94d89ea9b0a1aee5..696d940b42789d9c523090c1413edbdd4bf80b5a 100644
--- a/core/Settings/UserSetting.php
+++ b/core/Settings/UserSetting.php
@@ -14,8 +14,8 @@ use Piwik\Common;
use Piwik\Piwik;
/**
- * Describes a per user setting. Each user will be able to change this setting but each user
- * can set a different value. Changes from one user will not affect other users.
+ * Describes a per user setting. Each user will be able to change this setting for themselves,
+ * but not for other users.
*
* @package Piwik
* @subpackage Settings
@@ -39,7 +39,7 @@ class UserSetting extends Setting
$this->setUserLogin($userLogin);
- $this->displayedForCurrentUser = !Piwik::isUserIsAnonymous() && Piwik::isUserHasSomeViewAccess();
+ $this->displayedForCurrentUser = Piwik::isUserHasSomeViewAccess();
}
/**
diff --git a/core/SettingsPiwik.php b/core/SettingsPiwik.php
index 58ac848a9a5175fce29f9396d2f54584398cc0e1..353256e7d76bb56f1a427319799eeef6d4b04102 100644
--- a/core/SettingsPiwik.php
+++ b/core/SettingsPiwik.php
@@ -51,10 +51,9 @@ class SettingsPiwik
public static $cachedKnownSegmentsToArchive = null;
/**
- * Returns the list of stored segments to pre-process for all sites when executing cron archiving.
+ * Returns every stored segment to pre-process for each site during cron archiving.
*
* @return array The list of stored segments that apply to all sites.
- * @api
*/
public static function getKnownSegmentsToArchive()
{
@@ -159,7 +158,7 @@ class SettingsPiwik
static public $piwikUrlCache = null;
/**
- * Returns the URL to this Piwik instance, eg. http://demo.piwik.org/ or http://example.org/piwik/.
+ * Returns the URL to this Piwik instance, eg. **http://demo.piwik.org/** or **http://example.org/piwik/**.
*
* @return string
* @api
@@ -196,7 +195,7 @@ class SettingsPiwik
}
/**
- * Returns true if segmentation is allowed for this user, false if otherwise.
+ * Returns `true` if segmentation is allowed for this user, `false` if otherwise.
*
* @return bool
* @api
@@ -210,9 +209,8 @@ class SettingsPiwik
/**
* Returns true if unique visitors should be processed for the given period type.
*
- * Unique visitor processing is controlled by the **[General] enable_processing_unique_visitors_...**
- * INI config options. By default, day/week/month periods always process unique visitors and
- * year/range are not.
+ * Unique visitor processing is controlled by the `[General] enable_processing_unique_visitors_...`
+ * INI config options. By default, unique visitors are processed only for day/week/month periods.
*
* @param string $periodLabel `"day"`, `"week"`, `"month"`, `"year"` or `"range"`
* @return bool
diff --git a/core/SettingsServer.php b/core/SettingsServer.php
index c43b1f9502a3e126ee8192fc286bbdf618ec9693..0e6baf131d5b87359e5c5639a7df63a59d31841e 100644
--- a/core/SettingsServer.php
+++ b/core/SettingsServer.php
@@ -12,14 +12,15 @@ namespace Piwik;
/**
* Contains helper methods that can be used to get information regarding the
- * server, its settings and PHP settings.
+ * server, its settings and currently used PHP settings.
*
* @package Piwik
*/
class SettingsServer
{
/**
- * Returns true if the current script execution was triggered misc/cron/archive.php.
+ * Returns true if the current script execution was triggered by the cron archiving
+ * script (**misc/cron/archive.php**).
*
* Helpful for error handling: directly throw error without HTML (eg. when DB is down).
*
@@ -33,7 +34,7 @@ class SettingsServer
}
/**
- * Returns true if running on Microsoft IIS 7 (or above), false if otherwise.
+ * Returns `true` if running on Microsoft IIS 7 (or above), `false` if otherwise.
*
* @return bool
* @api
@@ -48,7 +49,7 @@ class SettingsServer
}
/**
- * Returns true if running on an Apache web server, false if otherwise.
+ * Returns `true` if running on an Apache web server, `false` if otherwise.
*
* @return bool
* @api
@@ -62,7 +63,7 @@ class SettingsServer
}
/**
- * Returns true if running on a Windows operating system, false if otherwise.
+ * Returns `true` if running on a Windows operating system, `false` if otherwise.
*
* @since 0.6.5
* @return bool
@@ -74,8 +75,8 @@ class SettingsServer
}
/**
- * Returns true if this php version/build supports timezone manipulation
- * (e.g., php >= 5.2, or compiled with EXPERIMENTAL_DATE_SUPPORT=1 for
+ * Returns `true` if this PHP version/build supports timezone manipulation
+ * (e.g., php >= 5.2, or compiled with **EXPERIMENTAL_DATE_SUPPORT=1** for
* php < 5.2).
*
* @return bool
@@ -92,9 +93,9 @@ class SettingsServer
}
/**
- * Returns true if the GD PHP extension is available, false if otherwise.
+ * Returns `true` if the GD PHP extension is available, `false` if otherwise.
*
- * ImageGraph and sparklines depend on the GD extension.
+ * _Note: ImageGraph and the sparkline report visualization depend on the GD extension._
*
* @return bool
* @api
diff --git a/core/UrlHelper.php b/core/UrlHelper.php
index f6daa0734d3d9f2825d2abeef51e9b7593ab0934..7092906aa76db66cbdd184078765134113ee9f98 100644
--- a/core/UrlHelper.php
+++ b/core/UrlHelper.php
@@ -19,8 +19,7 @@ class UrlHelper
{
/**
* Converts an array of query parameter name/value mappings into a query string.
- * Parameters that are in `$parametersToExclude` will not appear in the result
- * query string.
+ * Parameters that are in `$parametersToExclude` will not appear in the result.
*
* @static
* @param $queryParameters Array of query parameters, eg, `array('site' => '0', 'date' => '2012-01-01')`.
@@ -113,7 +112,7 @@ class UrlHelper
* Returns a URL created from the result of the [parse_url](http://php.net/manual/en/function.parse-url.php)
* function.
*
- * Copied from the PHP comments at http://php.net/parse_url
+ * Copied from the PHP comments at [http://php.net/parse_url](http://php.net/parse_url).
*
* @param array $parsed Result of [parse_url](http://php.net/manual/en/function.parse-url.php).
* @return false|string The URL or `false` if `$parsed` isn't an array.
@@ -144,7 +143,7 @@ class UrlHelper
/**
* Returns a URL query string as an array.
*
- * @param string $urlQuery The query string.
+ * @param string $urlQuery The query string, eg, `'?param1=value1¶m2=value2'`.
* @return array eg, `array('param1' => 'value1', 'param2' => 'value2')`
* @api
*/
@@ -221,7 +220,7 @@ class UrlHelper
/**
* Returns the path and query string of a URL.
*
- * @param string $url
+ * @param string $url The URL.
* @return string eg, `/test/index.php?module=CoreHome` if `$url` is `http://piwik.org/test/index.php?module=CoreHome`.
* @api
*/
diff --git a/core/WidgetsList.php b/core/WidgetsList.php
index a3b1098940c8560a5b04c1dd30a14bcd5f8dda2f..d2c2c63cc7acbe489c020761d7fe080c3eaed757 100644
--- a/core/WidgetsList.php
+++ b/core/WidgetsList.php
@@ -14,7 +14,7 @@ namespace Piwik;
* Manages the global list of reports that can be displayed as dashboard widgets.
*
* Reports are added as dashboard widgets through the {@hook WidgetsList.addWidgets}
- * event. Plugins should call {@link add()} in event observers for this event.
+ * event. Observers for this event should call the {@link add()} method to add reports.
*
* @package PluginsFunctions
* @api
@@ -38,12 +38,12 @@ class WidgetsList
/**
* Returns all available widgets.
*
- * @return array Maps widget categories with an array of widget information, eg,
+ * @return array Array Mapping widget categories with an array of widget information, eg,
* ```
* array(
* 'Visitors' => array(
- * array(...),
- * array(...)
+ * array(...), // info about first widget in this category
+ * array(...) // info about second widget in this category, etc.
* ),
* 'Visits' => array(
* array(...),
@@ -157,11 +157,11 @@ class WidgetsList
}
/**
- * Removes one more widgets from the widget list.
+ * Removes one or more widgets from the widget list.
*
* @param string $widgetCategory The widget category. Can be a translation token.
* @param string|false $widgetName The name of the widget to remove. Cannot be a
- * translation token. If not supplied, entire category
+ * translation token. If not supplied, the entire category
* will be removed.
*/
static public function remove($widgetCategory, $widgetName = false)
@@ -179,11 +179,10 @@ class WidgetsList
}
/**
- * Returns true if the widget with the given parameters exists in the widget list,
- * false if otherwise.
+ * Returns `true` if a report exists in the widget list, `false` if otherwise.
*
- * @param string $controllerName The controller name of the widget's report.
- * @param string $controllerAction The controller action of the widget's report.
+ * @param string $controllerName The controller name of the report.
+ * @param string $controllerAction The controller action of the report.
* @return bool
*/
static public function isDefined($controllerName, $controllerAction)