diff options
| author | diosmosis <benakamoorthi@fastmail.fm> | 2013-12-08 22:12:48 +0400 |
|---|---|---|
| committer | diosmosis <benakamoorthi@fastmail.fm> | 2013-12-08 22:13:07 +0400 |
| commit | 13297a804c38999aa790af93f1d599e3c809dc7d (patch) | |
| tree | cdf7cb0b4df018853852a1af675041cd23944293 | |
| parent | 54bb5200d2567e51ff5a77dcd4dfa89195c169d9 (diff) | |
Fixes #4200, revised rest of @api classes/methods, closing ticket.
52 files changed, 453 insertions, 338 deletions
diff --git a/core/Access.php b/core/Access.php index 86a4a04cf5..3ca89ff2a6 100644 --- a/core/Access.php +++ b/core/Access.php @@ -13,27 +13,25 @@ namespace Piwik; use Piwik\Db; /** - * Class to handle User Access: - * - loads user access from the AuthResult object - * - provides easy to use API to check the permissions for the current (check* methods) + * Singleton that manages user access to Piwik resources. + * + * To check whether a user has access to a resource, use one of the {@link Piwik Piwik::checkUser...} + * methods. * - * In Piwik there are mainly 4 access levels - * - no access - * - VIEW access - * - ADMIN access - * - Super admin access - * - * An access level is on a per website basis. - * A given user has a given access level for a given website. - * For example: - * User Noemie has - * - VIEW access on the website 1, - * - ADMIN on the website 2 and 4, and - * - NO access on the website 3 and 5 - * - * There is only one Super User. He has ADMIN access to all the websites - * and he only can change the main configuration settings. + * In Piwik there are four different access levels: + * + * - **no access**: Users with this access level cannot view the resource. + * - **view access**: Users with this access level can view the resource, but cannot modify it. + * - **admin access**: Users with this access level can view and modify the resource. + * - **super user access**: Only the super user has this access level. It means the user can do + * whatever he/she wants. + * + * Super user access is required to set some configuration options. + * All other options are specific to the user or to a website. * + * Access is granted per website. Uses with access for a website can view all + * data associated with that website. + * * @package Piwik * @subpackage Access */ diff --git a/core/Archive.php b/core/Archive.php index d7f59e0ff8..67f66b7c9a 100644 --- a/core/Archive.php +++ b/core/Archive.php @@ -20,7 +20,7 @@ use Piwik\Period\Range; * The **Archive** class is used to query cached analytics statistics * (termed "archive data"). * - * You can use **Archive** instances to get archive data for one or more sites, + * You can use **Archive** instances to get data that was archived for one or more sites, * for one or more periods and one optional segment. * * If archive data is not found, this class will initiate the archiving process. [1](#footnote-1) @@ -37,7 +37,7 @@ use Piwik\Period\Range; * * ### Learn more * - * Learn more about _archiving_ [here](#). + * Learn more about _archiving_ [here](/guides/all-about-analytics-data). * * ### Limitations * @@ -103,7 +103,7 @@ use Piwik\Period\Range; * * <a name="footnote-1"></a> * [1]: The archiving process will not be launched if browser archiving is disabled - * and the current request came from a browser (and not the archive.php cron + * and the current request came from a browser (and not the **archive.php** cron * script). * * @package Piwik @@ -184,7 +184,7 @@ class Archive * sites and periods, using an optional Segment. * * This method uses data that is found in query parameters, so the parameters to this - * function can all be strings. + * function can be string values. * * If you want to create an Archive instance with an array of Period instances, use * {@link Archive::factory()}. @@ -267,9 +267,9 @@ class Archive * * @param string|array $names One or more archive names, eg, `'nb_visits'`, `'Referrers_distinctKeywords'`, * etc. - * @return mixed False if there is no data to return, a numeric if only we're not querying - * for multiple sites/dates, or an array if multiple sites, dates or names are - * queried for. + * @return false|numeric|array `false` if there is no data to return, a single numeric value if we're not querying + * for multiple sites/periods, or an array if multiple sites, periods or names are + * queried for. */ public function getNumeric($names) { @@ -292,7 +292,7 @@ class Archive /** * Queries and returns blob data in an array. * - * Reports are stored in blobs as serialized arrays of DataTable\Row instances, but this + * Reports are stored in blobs as serialized arrays of {@link DataTable\Row} instances, but this * data can technically be anything. In other words, you can store whatever you want * as archive data blobs. * @@ -324,14 +324,14 @@ class Archive * be a DataTable\Map that is indexed by site ID. * * If multiple periods were requested in {@link build()} or {@link factory()} the result will - * be a DataTable\Map that is indexed by period. + * be a {@link DataTable\Map} that is indexed by period. * * The site ID index is always first, so if multiple sites & periods were requested, the result - * will be a DataTable\Map indexed by site ID which contains DataTable\Map instances that are + * will be a {@link DataTable\Map} indexed by site ID which contains {@link DataTable\Map} instances that are * indexed by period. * - * Note: Every DataTable instance returned will have at most one row in it. The contents of each - * row will be the requested metrics for the appropriate site and period. + * _Note: Every DataTable instance returned will have at most one row in it. The contents of each + * row will be the requested metrics for the appropriate site and period._ * * @param string|array $names One or more archive names, eg, 'nb_visits', 'Referrers_distinctKeywords', * etc. @@ -345,25 +345,25 @@ class Archive } /** - * Queries and returns a single report as a DataTable instance. + * Queries and returns one or more reports as DataTable instances. * - * This method will query blob data that is a serialized array of of DataTable\Row's and + * This method will query blob data that is a serialized array of of {@link DataTable\Row}'s and * unserialize it. * * If multiple sites were requested in {@link build()} or {@link factory()} the result will - * be a DataTable\Map that is indexed by site ID. + * be a {@link DataTable\Map} that is indexed by site ID. * * If multiple periods were requested in {@link build()} or {@link factory()} the result will * be a DataTable\Map that is indexed by period. * * The site ID index is always first, so if multiple sites & periods were requested, the result - * will be a DataTable\Map indexed by site ID which contains DataTable\Map instances that are + * will be a {@link DataTable\Map} indexed by site ID which contains {@link DataTable\Map} instances that are * indexed by period. * * @param string $name The name of the record to get. This method can only query one record at a time. * @param int|string|null $idSubtable The ID of the subtable to get (if any). * @return DataTable|DataTable\Map A DataTable if multiple sites and periods were not requested. - * An appropriately indexed DataTable\Map if otherwise. + * An appropriately indexed {@link DataTable\Map} if otherwise. */ public function getDataTable($name, $idSubtable = null) { @@ -381,7 +381,7 @@ class Archive * be a DataTable\Map that is indexed by period. * * The site ID index is always first, so if multiple sites & periods were requested, the result - * will be a DataTable\Map indexed by site ID which contains DataTable\Map instances that are + * will be a {@link DataTable\Map indexed} by site ID which contains {@link DataTable\Map} instances that are * indexed by period. * * @param string $name The name of the record to get. diff --git a/core/Config.php b/core/Config.php index 48fff84be0..f9f8646fbe 100644 --- a/core/Config.php +++ b/core/Config.php @@ -194,9 +194,9 @@ class Config extends Singleton * If set, Piwik will use the hostname config no matter if it exists or not. Useful for instance if you want to * create a new hostname config: * - * $config = Config::getInstance(); - * $config->forceUsageOfHostnameConfig('piwik.example.com'); - * $config->save(); + * $config = Config::getInstance(); + * $config->forceUsageOfHostnameConfig('piwik.example.com'); + * $config->save(); * * @param string $hostname eg piwik.example.com * @@ -217,7 +217,7 @@ class Config extends Singleton } /** - * Is local configuration file writable? + * Returns `true` if the local configuration file is writable. * * @return bool */ @@ -542,7 +542,8 @@ class Config extends Singleton } /** - * Writes the current configuration to `config.ini.php`. + * Writes the current configuration to the **config.ini.php** file. Only writes options whose + * values are different from the default. * * @api */ diff --git a/core/DataTable/Filter.php b/core/DataTable/Filter.php index 58bede7b8e..99bcd08c85 100644 --- a/core/DataTable/Filter.php +++ b/core/DataTable/Filter.php @@ -50,7 +50,7 @@ abstract class Filter } /** - * Filters the supplied DataTable. + * Manipulates a {@link DataTable} in some way. * * @param DataTable $table */ diff --git a/core/DataTable/Filter/AddColumnsProcessedMetrics.php b/core/DataTable/Filter/AddColumnsProcessedMetrics.php index a141a3732c..53f555a274 100644 --- a/core/DataTable/Filter/AddColumnsProcessedMetrics.php +++ b/core/DataTable/Filter/AddColumnsProcessedMetrics.php @@ -16,13 +16,13 @@ use Piwik\DataTable; use Piwik\Metrics; /** - * Adds processed metrics columns to a DataTable using metrics that already exist. + * Adds processed metrics columns to a {@link DataTable} using metrics that already exist. * * Columns added are: * * - **conversion_rate**: percent value of `nb_visits_converted / nb_visits * - **nb_actions_per_visit**: `nb_actions / nb_visits` - * - **avg_time_on_site**: in number of seconds, `round(visit_length / nb_visits)`. not + * - **avg_time_on_site**: in number of seconds, `round(visit_length / nb_visits)`. Not * pretty formatted. * - **bounce_rate**: percent value of `bounce_count / nb_visits` * diff --git a/core/DataTable/Filter/AddColumnsProcessedMetricsGoal.php b/core/DataTable/Filter/AddColumnsProcessedMetricsGoal.php index 976379d136..494a8907e1 100644 --- a/core/DataTable/Filter/AddColumnsProcessedMetricsGoal.php +++ b/core/DataTable/Filter/AddColumnsProcessedMetricsGoal.php @@ -17,7 +17,7 @@ use Piwik\Piwik; use Piwik\Tracker\GoalManager; /** - * Adds the Goal related metrics to a DataTable using metrics that already exist. + * Adds goal related metrics to a {@link DataTable} using metrics that already exist. * * Metrics added are: * - **revenue_per_visit**: total goal and ecommerce revenue / nb_visits @@ -42,7 +42,7 @@ use Piwik\Tracker\GoalManager; * Adding the **filter_update_columns_when_show_all_goals** query parameter to * an API request will trigger the execution of this Filter. * - * Note: This filter must be called before {@link ReplaceColumnNames} is called. + * _Note: This filter must be called before {@link ReplaceColumnNames} is called._ * * **Basic usage example** * diff --git a/core/DataTable/Filter/AddSummaryRow.php b/core/DataTable/Filter/AddSummaryRow.php index 8d6402514d..80bf0e8a94 100644 --- a/core/DataTable/Filter/AddSummaryRow.php +++ b/core/DataTable/Filter/AddSummaryRow.php @@ -15,8 +15,7 @@ use Piwik\DataTable; use Piwik\DataTable\Row\DataTableSummaryRow; /** - * Add a summary row row to the table that is the sum of all other table - * rows. + * Adds a summary row to {@link DataTable}s that contains the sum of all other table rows. * * **Basic usage example** * diff --git a/core/DataTable/Filter/BeautifyRangeLabels.php b/core/DataTable/Filter/BeautifyRangeLabels.php index b2f6e9eac7..723ec42398 100644 --- a/core/DataTable/Filter/BeautifyRangeLabels.php +++ b/core/DataTable/Filter/BeautifyRangeLabels.php @@ -14,15 +14,15 @@ use Piwik\DataTable; use Piwik\Piwik; /** - * A DataTable filter that replaces range label columns with prettier, + * A {@link DataTable} filter that replaces range label columns with prettier, * human-friendlier versions. * * When reports that summarize data over a set of ranges (such as the - * reports in the VisitorInterest plugin) are archived, they are + * reports in the **VisitorInterest** plugin) are archived, they are * archived with labels that read as: '$min-$max' or '$min+'. These labels * have no units and can look like '1-1'. * - * This filter can be used to clean up and add units those range labels. To + * This filter can be used to clean up and add units to those range labels. To * do this, you supply a string to use when the range specifies only * one unit (ie '1-1') and another format string when the range specifies * more than one unit (ie '2-2', '3-5' or '6+'). diff --git a/core/DataTable/Filter/BeautifyTimeRangeLabels.php b/core/DataTable/Filter/BeautifyTimeRangeLabels.php index 786ae05103..5ca3a0749b 100644 --- a/core/DataTable/Filter/BeautifyTimeRangeLabels.php +++ b/core/DataTable/Filter/BeautifyTimeRangeLabels.php @@ -13,7 +13,7 @@ namespace Piwik\DataTable\Filter; use Piwik\DataTable; /** - * A DataTable filter that replaces range labels whose values are in seconds with + * A {@link DataTable} filter that replaces range labels whose values are in seconds with * prettier, human-friendlier versions. * * This filter customizes the behavior of the {@link BeautifyRangeLabels} filter diff --git a/core/DataTable/Filter/CalculateEvolutionFilter.php b/core/DataTable/Filter/CalculateEvolutionFilter.php index 6ca526d0fc..2377df89ce 100755 --- a/core/DataTable/Filter/CalculateEvolutionFilter.php +++ b/core/DataTable/Filter/CalculateEvolutionFilter.php @@ -15,12 +15,12 @@ use Piwik\DataTable\Row; use Piwik\Site; /** - * A DataTable filter that calculates the evolution of a metric and adds + * A {@link DataTable} filter that calculates the evolution of a metric and adds * it to each row as a percentage. * * **This filter cannot be used as an argument to {@link Piwik\DataTable::filter()}** since - * it requires corresponding data from another datatable. Instead, to use it, - * you must manually perform a binary filter (see the MultiSites API for an + * it requires corresponding data from another DataTable. Instead, + * you must manually perform a binary filter (see the **MultiSites** API for an * example). * * The evolution metric is calculated as: diff --git a/core/DataTable/Filter/ColumnCallbackAddColumn.php b/core/DataTable/Filter/ColumnCallbackAddColumn.php index ea3fa74585..d65d844e9c 100755 --- a/core/DataTable/Filter/ColumnCallbackAddColumn.php +++ b/core/DataTable/Filter/ColumnCallbackAddColumn.php @@ -14,7 +14,7 @@ use Piwik\DataTable; use Piwik\DataTable\Filter; /** - * Adds a new column to every row of a DataTable based on the result of callback. + * Adds a new column to every row of a {@link DataTable} based on the result of callback. * * **Basic usage example** * diff --git a/core/DataTable/Filter/ColumnCallbackAddColumnPercentage.php b/core/DataTable/Filter/ColumnCallbackAddColumnPercentage.php index a6ce836eb9..23656eb0b8 100644 --- a/core/DataTable/Filter/ColumnCallbackAddColumnPercentage.php +++ b/core/DataTable/Filter/ColumnCallbackAddColumnPercentage.php @@ -13,7 +13,7 @@ namespace Piwik\DataTable\Filter; use Piwik\Piwik; /** - * Calculates a percentage value for each row of a DataTable and adds the result + * Calculates a percentage value for each row of a {@link DataTable} and adds the result * to each row. * * See {@link ColumnCallbackAddColumnQuotient} for more information. diff --git a/core/DataTable/Filter/ColumnCallbackAddColumnQuotient.php b/core/DataTable/Filter/ColumnCallbackAddColumnQuotient.php index a36f7de04b..47d3825cb5 100644 --- a/core/DataTable/Filter/ColumnCallbackAddColumnQuotient.php +++ b/core/DataTable/Filter/ColumnCallbackAddColumnQuotient.php @@ -21,6 +21,10 @@ use Piwik\DataTable\Row; * This filter is used to calculate rate values (eg, `'bounce_rate'`), averages * (eg, `'avg_time_on_page'`) and other types of values. * + * **Basic usage example** + * + * $dataTable->queueFilter('ColumnCallbackAddColumnQuotient', array('bounce_rate', 'bounce_count', 'nb_visits', $precision = 2)); + * * @package Piwik * @subpackage DataTable * @api @@ -51,7 +55,8 @@ class ColumnCallbackAddColumnQuotient extends Filter * @param bool $getDivisorFromSummaryRow Whether to get the divisor from the summary row or the current * row iteration. */ - public function __construct($table, $columnNameToAdd, $columnValueToRead, $divisorValueOrDivisorColumnName, $quotientPrecision = 0, $shouldSkipRows = false, $getDivisorFromSummaryRow = false) + public function __construct($table, $columnNameToAdd, $columnValueToRead, $divisorValueOrDivisorColumnName, + $quotientPrecision = 0,$shouldSkipRows = false, $getDivisorFromSummaryRow = false) { parent::__construct($table); $this->table = $table; diff --git a/core/DataTable/Filter/ColumnCallbackAddMetadata.php b/core/DataTable/Filter/ColumnCallbackAddMetadata.php index bbc4584e61..f9a092457f 100644 --- a/core/DataTable/Filter/ColumnCallbackAddMetadata.php +++ b/core/DataTable/Filter/ColumnCallbackAddMetadata.php @@ -14,8 +14,8 @@ use Piwik\DataTable; use Piwik\DataTable\Filter; /** - * Executes a callback for each row of a DataTable and adds the result as a new - * metadata column. + * Executes a callback for each row of a {@link DataTable} and adds the result as a new + * row metadata value. * * **Basic usage example** * diff --git a/core/DataTable/Filter/ColumnCallbackDeleteRow.php b/core/DataTable/Filter/ColumnCallbackDeleteRow.php index 7ba14e7d1e..cab41a039d 100644 --- a/core/DataTable/Filter/ColumnCallbackDeleteRow.php +++ b/core/DataTable/Filter/ColumnCallbackDeleteRow.php @@ -14,7 +14,7 @@ use Piwik\DataTable; use Piwik\DataTable\Filter; /** - * Delete all rows for which a callback returns true. // TODO: modify + * Deletes all rows for which a callback returns true. * * **Basic usage example** * diff --git a/core/DataTable/Filter/ColumnDelete.php b/core/DataTable/Filter/ColumnDelete.php index 540c7c783a..9a63f2b735 100644 --- a/core/DataTable/Filter/ColumnDelete.php +++ b/core/DataTable/Filter/ColumnDelete.php @@ -14,7 +14,7 @@ use Piwik\DataTable; use Piwik\DataTable\Filter; /** - * Filter that will remove columns from a DataTable using either a blacklist, + * Filter that will remove columns from a {@link DataTable} using either a blacklist, * whitelist or both. * * This filter is used to handle the **hideColumn** and **showColumn** query parameters. @@ -27,7 +27,6 @@ use Piwik\DataTable\Filter; * $columnsToKeep = array('nb_visits'); * $dataTable->filter('ColumnDelete', array(array(), $columnsToKeep)); * - * * @package Piwik * @subpackage DataTable * @api @@ -93,8 +92,7 @@ class ColumnDelete extends Filter } /** - * Filters the given DataTable. Removes columns that are not desired from - * each DataTable row. + * See {@link ColumnDelete}. * * @param DataTable $table */ diff --git a/core/DataTable/Filter/ExcludeLowPopulation.php b/core/DataTable/Filter/ExcludeLowPopulation.php index 756efcd18c..e998aa321d 100644 --- a/core/DataTable/Filter/ExcludeLowPopulation.php +++ b/core/DataTable/Filter/ExcludeLowPopulation.php @@ -15,7 +15,7 @@ use Piwik\DataTable\Filter; /** * Deletes all rows for which a specific column has a value that is lower than - * specific minimum threshold value. + * specified minimum threshold value. * * **Basic usage examples** * @@ -52,13 +52,13 @@ class ExcludeLowPopulation extends Filter * * @param DataTable $table The DataTable that will be filtered eventually. * @param string $columnToFilter The name of the column whose value will determine whether - * row is deleted or not. + * a row is deleted or not. * @param number|false $minimumValue The minimum column value. Rows with column values < * this number will be deleted. If false, * `$minimumPercentageThreshold` is used. * @param bool|float $minimumPercentageThreshold If supplied, column values must be a greater * percentage of the sum of all column values than - * this value. + * this precentage. */ public function __construct($table, $columnToFilter, $minimumValue, $minimumPercentageThreshold = false) { diff --git a/core/DataTable/Filter/GroupBy.php b/core/DataTable/Filter/GroupBy.php index 08f99c3e44..0eef76c0d1 100755 --- a/core/DataTable/Filter/GroupBy.php +++ b/core/DataTable/Filter/GroupBy.php @@ -14,10 +14,10 @@ use Piwik\DataTable; use Piwik\DataTable\Filter; /** - * DataTable filter that will group DataTable rows together based on the results + * DataTable filter that will group {@link DataTable} rows together based on the results * of a reduce function. Rows with the same reduce result will be summed and merged. * - * NOTE: This filter should never be queued, it must be applied directly on a DataTable. + * _NOTE: This filter should never be queued, it must be applied directly on a {@link DataTable}._ * * **Basic usage example** * diff --git a/core/DataTable/Filter/Limit.php b/core/DataTable/Filter/Limit.php index 875f50ab23..dd990223d6 100644 --- a/core/DataTable/Filter/Limit.php +++ b/core/DataTable/Filter/Limit.php @@ -14,7 +14,7 @@ use Piwik\DataTable; use Piwik\DataTable\Filter; /** - * Delete all rows from the table that are not in the given offset -> offset+limit range. + * Delete all rows from the table that are not in the given [offset, offset+limit) range. * * **Basic example usage** * diff --git a/core/DataTable/Filter/MetadataCallbackAddMetadata.php b/core/DataTable/Filter/MetadataCallbackAddMetadata.php index 342f935780..b9a88b08b3 100644 --- a/core/DataTable/Filter/MetadataCallbackAddMetadata.php +++ b/core/DataTable/Filter/MetadataCallbackAddMetadata.php @@ -14,7 +14,7 @@ use Piwik\DataTable; use Piwik\DataTable\Filter; /** - * Executes a callback for each row of a DataTable and adds the result to the + * Executes a callback for each row of a {@link DataTable} and adds the result to the * row as a metadata value. Only metadata values are passed to the callback. * * **Basic usage example** diff --git a/core/DataTable/Filter/MetadataCallbackReplace.php b/core/DataTable/Filter/MetadataCallbackReplace.php index bc326e3a14..6a2954d0e4 100644 --- a/core/DataTable/Filter/MetadataCallbackReplace.php +++ b/core/DataTable/Filter/MetadataCallbackReplace.php @@ -14,8 +14,8 @@ use Piwik\DataTable; use Piwik\DataTable\Row; /** - * Execute a callback for each row of a DataTable using certain column values and metadata - * and replaces row metadata with the result. + * Execute a callback for each row of a {@link DataTable} passing certain column values and metadata + * as metadata, and replaces row metadata with the callback result. * * **Basic usage example** * diff --git a/core/DataTable/Filter/PatternRecursive.php b/core/DataTable/Filter/PatternRecursive.php index db33d5a786..0970a1d29e 100644 --- a/core/DataTable/Filter/PatternRecursive.php +++ b/core/DataTable/Filter/PatternRecursive.php @@ -16,8 +16,8 @@ use Piwik\DataTable; use Piwik\DataTable\Manager; /** - * Deletes rows for which a specific column in both the row and all subtables that - * descend from the row do not match a supplied regex pattern. + * Deletes rows that do not contain a column that matches a regex pattern and do not contain a + * subtable that contains a column that matches a regex pattern. * * **Example** * diff --git a/core/DataTable/Filter/ReplaceColumnNames.php b/core/DataTable/Filter/ReplaceColumnNames.php index 2a8adf4ddc..02c8f9f500 100644 --- a/core/DataTable/Filter/ReplaceColumnNames.php +++ b/core/DataTable/Filter/ReplaceColumnNames.php @@ -51,10 +51,10 @@ class ReplaceColumnNames extends Filter * @param DataTable $table The table that will be eventually filtered. * @param array|null $mappingToApply The name mapping to apply. Must map old column names * with new ones, eg, - * ``` - * array('OLD_COLUMN_NAME' => 'NEW_COLUMN NAME', - * 'OLD_COLUMN_NAME2' => 'NEW_COLUMN NAME2') - * ``` + * + * array('OLD_COLUMN_NAME' => 'NEW_COLUMN NAME', + * 'OLD_COLUMN_NAME2' => 'NEW_COLUMN NAME2') + * * If null, {@link Piwik\Metrics::$mappingFromIdToName} is used. */ public function __construct($table, $mappingToApply = null) diff --git a/core/DataTable/Filter/ReplaceSummaryRowLabel.php b/core/DataTable/Filter/ReplaceSummaryRowLabel.php index 8fb998b9e6..bb1d15df46 100644 --- a/core/DataTable/Filter/ReplaceSummaryRowLabel.php +++ b/core/DataTable/Filter/ReplaceSummaryRowLabel.php @@ -19,10 +19,10 @@ use Piwik\Piwik; * Replaces the label of the summary row with a supplied label. * * This filter is only used to prettify the summary row label and so it should - * always be queued on a DataTable. + * always be queued on a {@link DataTable}. * - * This filter always recurses. In other words, this filter will apply itself to - * all subtables in the given DataTable's hierarchy. + * This filter always recurses. In other words, this filter will always apply itself to + * all subtables in the given {@link DataTable}'s table hierarchy. * * **Basic example** * @@ -75,4 +75,4 @@ class ReplaceSummaryRowLabel extends Filter } } } -} +}
\ No newline at end of file diff --git a/core/DataTable/Filter/Sort.php b/core/DataTable/Filter/Sort.php index 3976a2417b..16ebd80dc4 100644 --- a/core/DataTable/Filter/Sort.php +++ b/core/DataTable/Filter/Sort.php @@ -17,8 +17,9 @@ use Piwik\DataTable; use Piwik\Metrics; /** - * Sorts a DataTable based on the value of a specific column. - * Possible to specify a natural sorting (see php.net/natsort for details) + * Sorts a {@link DataTable} based on the value of a specific column. + * + * It is possible to specify a natural sorting (see [php.net/natsort](http://php.net/natsort) for details). * * @package Piwik * @subpackage DataTable @@ -186,7 +187,7 @@ class Sort extends Filter } /** - * Sorts the given data table by defined column and sorting method + * See {@link Sort}. * * @param DataTable $table * @return mixed diff --git a/core/DataTable/Filter/Truncate.php b/core/DataTable/Filter/Truncate.php index ecfff67b76..5896048a6a 100644 --- a/core/DataTable/Filter/Truncate.php +++ b/core/DataTable/Filter/Truncate.php @@ -16,8 +16,8 @@ use Piwik\DataTable\Row; use Piwik\Piwik; /** - * Truncates a DataTable by merging all rows after a certain index into a new summary - * row, unless the count of rows is less than the index. + * Truncates a {@link DataTable} by merging all rows after a certain index into a new summary + * row. If the count of rows is less than the index, nothing happens. * * The {@link ReplaceSummaryRowLabel} filter will be queued after the table is truncated. * @@ -85,7 +85,7 @@ class Truncate extends Filter } } - public function addSummaryRow($table) + private function addSummaryRow($table) { $table->filter('Sort', array($this->columnToSortByBeforeTruncating, 'desc')); diff --git a/core/DataTable/Map.php b/core/DataTable/Map.php index a0d42795c6..0f9ef069b8 100644 --- a/core/DataTable/Map.php +++ b/core/DataTable/Map.php @@ -14,13 +14,13 @@ use Piwik\DataTable; use Piwik\DataTable\Renderer\Console; /** - * Stores an array of DataTables indexed by one type of DataTable metadata (such as site ID + * Stores an array of {@link DataTable}s indexed by one type of {@link DataTable} metadata (such as site ID * or period). * * DataTable Maps are returned on all queries that involve multiple sites and/or multiple - * periods. The Maps will contain a DataTable for each site and period combination. + * periods. The Maps will contain a {@link DataTable} for each site and period combination. * - * The Map implements some of the features of the DataTable such as queueFilter and getRowsCount. + * The Map implements some {@link DataTable} such as {@link queueFilter()} and {@link getRowsCount}. * * @package Piwik * @subpackage DataTable @@ -55,7 +55,7 @@ class Map implements DataTableInterface } /** - * Set the keyName. See {@link getKeyName()}. + * Set the name of they metadata used to index {@link DataTable}s. See {@link getKeyName()}. * * @param string $name */ @@ -65,7 +65,7 @@ class Map implements DataTableInterface } /** - * Returns the number of DataTables in this DataTable\Map. + * Returns the number of {@link DataTable}s in this DataTable\Map. * * @return int */ @@ -75,7 +75,7 @@ class Map implements DataTableInterface } /** - * Queue a filter to DataTable child of contained by this instance. + * Queue a filter to {@link DataTable} child of contained by this instance. * * See {@link Piwik\DataTable::queueFilter()} for more information.. * @@ -134,7 +134,7 @@ class Map implements DataTableInterface } /** - * Returns the first DataTable in the DataTable array. + * Returns the first element in the Map's array. * * @return DataTable|Map|false */ @@ -144,7 +144,7 @@ class Map implements DataTableInterface } /** - * Returns the last DataTable in the DataTable array. + * Returns the last element in the Map's array. * * @return DataTable|Map|false */ @@ -154,9 +154,9 @@ class Map implements DataTableInterface } /** - * Adds a new DataTable to the DataTable\Map. + * Adds a new {@link DataTable} or Map instance to this DataTable\Map. * - * @param DataTable $table + * @param DataTable|Map $table * @param string $label Label used to index this table in the array. */ public function addTable($table, $label) @@ -165,7 +165,7 @@ class Map implements DataTableInterface } /** - * Returns a string output of this DataTable\Map (applying the default renderer to every DataTable + * Returns a string output of this DataTable\Map (applying the default renderer to every {@link DataTable} * of this DataTable\Map). * * @return string @@ -178,7 +178,7 @@ class Map implements DataTableInterface } /** - * @see DataTable::enableRecursiveSort() + * See {@link DataTable::enableRecursiveSort()}. */ public function enableRecursiveSort() { @@ -188,9 +188,10 @@ class Map implements DataTableInterface } /** - * Renames the given column in each contained DataTable. + * Renames the given column in each contained {@link DataTable}. * - * @see DataTable::renameColumn + * See {@link DataTable::renameColumn()}. + * * @param string $oldName * @param string $newName */ @@ -202,9 +203,10 @@ class Map implements DataTableInterface } /** - * Deletes the specified columns in each contained DataTable. + * Deletes the specified columns in each contained {@link DataTable}. * - * @see DataTable::deleteColumns + * See {@link DataTable::deleteColumns()}. + * * @param array $columns The columns to delete. * @param bool $deleteRecursiveInSubtables This param is currently not used. */ @@ -218,7 +220,7 @@ class Map implements DataTableInterface /** * Deletes a table from the array of DataTables. * - * @param string $id The label associated with DataTable. + * @param string $id The label associated with {@link DataTable}. */ public function deleteRow($id) { @@ -226,7 +228,7 @@ class Map implements DataTableInterface } /** - * Deletes the given column in every contained DataTable. + * Deletes the given column in every contained {@link DataTable}. * * @see DataTable::deleteColumn * @param string $name @@ -239,7 +241,7 @@ class Map implements DataTableInterface } /** - * Returns the array containing all row values in all data tables for the requested column. + * Returns the array containing all column values in all contained {@link DataTable}s for the requested column. * * @param string $name The column name. * @return array @@ -257,9 +259,9 @@ class Map implements DataTableInterface } /** - * Merges the rows of every child DataTable into a new DataTable and + * Merges the rows of every child {@link DataTable} into a new one and * returns it. This function will also set the label of the merged rows - * to the label of the DataTable they were originally from. + * to the label of the {@link DataTable} they were originally from. * * The result of this function is determined by the type of DataTable * this instance holds. If this DataTable\Map instance holds an array @@ -295,7 +297,7 @@ class Map implements DataTableInterface * Inner Label 1: * DataTable(row2[label = 'Outer Label 0'], row4[label = 'Outer Label 1']) * - * In addition, if this instance holds an array of DataTable\Maps, the + * If this instance holds an array of DataTable\Maps, the * metadata of the first child is used as the metadata of the result. * * This function can be used, for example, to smoosh IndexedBySite archive @@ -359,8 +361,9 @@ class Map implements DataTableInterface } /** - * Adds a DataTable to all the tables in this array. - * NOTE: Will only add `$tableToSum` if the childTable has some rows + * Sums a DataTable to all the tables in this array. + * + * _Note: Will only add `$tableToSum` if the childTable has some rows._ * * See {@link Piwik\DataTable::addDataTable()}. * @@ -377,7 +380,7 @@ class Map implements DataTableInterface * Returns a new DataTable\Map w/ child tables that have had their * subtables merged. * - * @see DataTable::mergeSubtables + * See {@link DataTable::mergeSubtables()}. * * @return Map */ @@ -422,7 +425,7 @@ class Map implements DataTableInterface } /** - * @see DataTable::getColumns() + * See {@link DataTable::getColumns()}. * * @return array */ diff --git a/core/DataTable/Row.php b/core/DataTable/Row.php index e7310935a4..147a7c0e9f 100644 --- a/core/DataTable/Row.php +++ b/core/DataTable/Row.php @@ -63,17 +63,16 @@ class Row * Constructor. * * @param array $row An array with the following structure: - * ``` - * array( - * Row::COLUMNS => array('label' => 'Piwik', - * 'column1' => 42, - * 'visits' => 657, - * 'time_spent' => 155744), - * Row::METADATA => array('logo' => 'test.png'), - * Row::DATATABLE_ASSOCIATED => $subtable // DataTable object - * // (but in the row only the ID will be stored) - * ) - * ``` + * + * array( + * Row::COLUMNS => array('label' => 'Piwik', + * 'column1' => 42, + * 'visits' => 657, + * 'time_spent' => 155744), + * Row::METADATA => array('logo' => 'test.png'), + * Row::DATATABLE_ASSOCIATED => $subtable // DataTable object + * // (but in the row only the ID will be stored) + * ) */ public function __construct($row = array()) { @@ -125,7 +124,7 @@ class Row } /** - * When destroyed, a row destroys its associated subTable if there is one + * When destroyed, a row destroys its associated subtable if there is one. * @ignore */ public function __destruct() @@ -166,7 +165,7 @@ class Row * Deletes the given column. * * @param string $name The column name. - * @return bool True on success, false if the column does not exist. + * @return bool `true` on success, `false` if the column does not exist. */ public function deleteColumn($name) { @@ -227,13 +226,12 @@ class Row * Returns the array containing all the columns. * * @return array Example: - * ``` - * array( - * 'column1' => VALUE, - * 'label' => 'www.php.net' - * 'nb_visits' => 15894, - * ) - * ``` + * + * array( + * 'column1' => VALUE, + * 'label' => 'www.php.net' + * 'nb_visits' => 15894, + * ) */ public function getColumns() { @@ -273,7 +271,7 @@ class Row * * See {@link Piwik\DataTable::addDataTable()} to learn how DataTables are summed. * - * @param DataTable $subTable Table to sum to this row's subtab.e. + * @param DataTable $subTable Table to sum to this row's subtable. */ public function sumSubtable(DataTable $subTable) { @@ -319,7 +317,7 @@ class Row } /** - * Returns true if the subtable is currently loaded in memory via {@link Piwik\DataTable\Manager}. + * Returns `true` if the subtable is currently loaded in memory via {@link Piwik\DataTable\Manager}. * * @return bool */ @@ -340,7 +338,7 @@ class Row } /** - * Set all the columns at once. Overwrites previously set columns. + * Set all the columns at once. Overwrites **all** previously set columns. * * @param array eg, `array('label' => 'www.php.net', 'nb_visits' => 15894)` */ @@ -375,7 +373,7 @@ class Row * Deletes one metadata value or all metadata values. * * @param bool|string $name Metadata name (omit to delete entire metadata). - * @return bool true on success, false if the column didn't exist + * @return bool `true` on success, `false` if the column didn't exist */ public function deleteMetadata($name = false) { @@ -536,7 +534,7 @@ class Row } /** - * Returns true if this row is the summary row, false if otherwise. This function + * Returns `true` if this row is the summary row, `false` if otherwise. This function * depends on the label of the row, and so, is not 100% accurate. * * @return bool @@ -624,6 +622,8 @@ class Row * * - they have exactly the same columns / metadata * - they have a subDataTable associated, then we check that both of them are the same. + * + * Column order is not important. * * @param \Piwik\DataTable\Row $row1 first to compare * @param \Piwik\DataTable\Row $row2 second to compare diff --git a/core/DataTable/Simple.php b/core/DataTable/Simple.php index a895321189..86662b3ba4 100644 --- a/core/DataTable/Simple.php +++ b/core/DataTable/Simple.php @@ -29,12 +29,11 @@ class Simple extends DataTable * values. * * @param array $array Array containing the rows, eg, - * ``` - * array( - * 'Label row 1' => $value1, - * 'Label row 2' => $value2, - * ) - * ``` + * + * array( + * 'Label row 1' => $value1, + * 'Label row 2' => $value2, + * ) */ public function addRowsFromArray($array) { diff --git a/core/Date.php b/core/Date.php index 5c2bbb9f66..a618b8749a 100644 --- a/core/Date.php +++ b/core/Date.php @@ -80,7 +80,7 @@ class Date * @param string|int $dateString `'today'`, `'yesterday'`, `'now'`, `'yesterdaySameTime'`, a string with * `'YYYY-MM-DD HH:MM:SS'` format or a unix timestamp. * @param string $timezone The timezone of `$dateString`. If specified, `$dateString` will be converted - * from UTC to this timezone before being used in the Date return value. + * from this timezone to UTC before being used in the Date return value. * @throws Exception If `$dateString` is in an invalid format or if the time is before * Tue, 06 Aug 1991. * @return Date @@ -268,7 +268,7 @@ class Date } /** - * Returns true if the current date is older than the given `$date`. + * Returns `true` if the current date is older than the given `$date`. * * @param Date $date * @return bool @@ -279,7 +279,7 @@ class Date } /** - * Returns true if the current date is earlier than the given `$date`. + * Returns `true` if the current date is earlier than the given `$date`. * * @param Date $date * @return bool @@ -373,7 +373,7 @@ class Date } /** - * Returns true if current date is today. + * Returns `true` if current date is today. * * @return bool */ diff --git a/core/FrontController.php b/core/FrontController.php index f45028272a..5bc091c1a0 100644 --- a/core/FrontController.php +++ b/core/FrontController.php @@ -20,7 +20,7 @@ use Piwik\Session; /** * This singleton dispatches requests to the appropriate plugin Controller. * - * Piwik uses this class for all requests that go through index.php. Plugins can + * Piwik uses this class for all requests that go through **index.php**. Plugins can * use it to call controller actions of other plugins. * * ### Examples @@ -32,7 +32,7 @@ use Piwik\Session; * $_GET['changeVisitAlpha'] = false; * $_GET['removeOldVisits'] = false; * $_GET['showFooterMessage'] = false; - * FrontController::getInstance()->dispatch('UserCountryMap', 'realtimeMap'); + * return FrontController::getInstance()->dispatch('UserCountryMap', 'realtimeMap'); * } * * **Using other plugin controller actions** @@ -46,7 +46,7 @@ use Piwik\Session; * * $view = new View('@MyPlugin/myPopupWithRealtimeMap.twig'); * $view->realtimeMap = $realtimeMap; - * echo $realtimeMap->render(); + * return $realtimeMap->render(); * } * * For a detailed explanation, see the documentation [here](http://piwik.org/docs/plugins/framework-overview). @@ -65,7 +65,7 @@ class FrontController extends Singleton public static $enableDispatch = true; /** - * Executes the requested plugin controller action. + * Executes the requested plugin controller method. * * See also {@link fetchDispatch()}. * @@ -73,10 +73,9 @@ class FrontController extends Singleton * there is not enough permission, etc. * * @param string $module The name of the plugin whose controller to execute, eg, `'UserCountryMap'`. - * @param string $action The controller action name, eg, `'realtimeMap'`. - * @param array $parameters Array of parameters to pass to the controller action method. - * @return void|mixed The returned value of the call. Often nothing as most controller actions echo, but do not - * return data. + * @param string $action The controller method name, eg, `'realtimeMap'`. + * @param array $parameters Array of parameters to pass to the controller method. + * @return void|mixed The returned value of the call. This is the output of the controller method. * @api */ public function dispatch($module = null, $action = null, $parameters = null) @@ -194,16 +193,17 @@ class FrontController extends Singleton } /** - * Executes the requested plugin controller action and returns the data the action echos. + * Executes the requested plugin controller method and returns the data, capturing anything the + * method `echo`s. * - * Note: If the plugin controller returns something, the return value is returned instead - * of whatever is in the output buffer. + * _Note: If the plugin controller returns something, the return value is returned instead + * of whatever is in the output buffer._ * * @param string $module The name of the plugin whose controller to execute, eg, `'UserCountryMap'`. * @param string $action The controller action name, eg, `'realtimeMap'`. * @param array $parameters Array of parameters to pass to the controller action method. * @return string The `echo`'d data or the return value of the controller action. - * @api + * @deprecated */ public function fetchDispatch($module = null, $actionName = null, $parameters = null) { diff --git a/core/Http.php b/core/Http.php index 67f67c9c08..2f087a382e 100644 --- a/core/Http.php +++ b/core/Http.php @@ -13,7 +13,9 @@ namespace Piwik; use Exception; /** - * Server-side http client to retrieve content from remote servers, and optionally save to a local file. + * Contains HTTP client related helper methods that can retrieve content from remote servers + * and optionally save to a local file. + * * Used to check for the latest Piwik version and download updates. * * @package Piwik @@ -71,9 +73,11 @@ class Http * is returned on failure. * If `$getExtendedInfo` is `true` and `$destinationPath` is not specified an array with * the following information is returned on success: - * - status => the HTTP status code - * - headers => the HTTP headers - * - data => the HTTP response data + * + * - **status**: the HTTP status code + * - **headers**: the HTTP headers + * - **data**: the HTTP response data + * * `false` is still returned on failure. * @api */ @@ -94,7 +98,7 @@ class Http } /** - * Sends http request using the specified transport method + * Sends an HTTP request using the specified transport method. * * @param string $method * @param string $aUrl @@ -543,8 +547,8 @@ class Http * is stored in the piwik_option table before starting a download. The expected * file size is obtained through a `HEAD` HTTP request. * - * Note: this function uses the `Range` HTTP header to accomplish downloading in - * parts. + * _Note: this function uses the **Range** HTTP header to accomplish downloading in + * parts. Not every server supports this header._ * * The proper use of this function is to call it once per request. The browser * should continue to send requests to Piwik which will in turn call this method @@ -553,40 +557,40 @@ class Http * * **Example Usage** * - * ``` - * // browser JavaScript - * var downloadFile = function (isStart) { - * var ajax = new ajaxHelper(); - * ajax.addParams({ - * module: 'MyPlugin', - * action: 'myAction', - * isStart: isStart ? 1 : 0 - * }, 'post'); - * ajax.setCallback(function (response) { - * var progress = response.progress - * // ...update progress... + * ``` + * // browser JavaScript + * var downloadFile = function (isStart) { + * var ajax = new ajaxHelper(); + * ajax.addParams({ + * module: 'MyPlugin', + * action: 'myAction', + * isStart: isStart ? 1 : 0 + * }, 'post'); + * ajax.setCallback(function (response) { + * var progress = response.progress + * // ...update progress... * - * downloadFile(false); - * }); - * ajax.send(); - * } + * downloadFile(false); + * }); + * ajax.send(); + * } * - * downloadFile(true); - * ``` + * downloadFile(true); + * ``` * - * ``` - * // PHP controller action - * public function myAction() - * { - * $outputPath = PIWIK_INCLUDE_PATH . '/tmp/averybigfile.zip'; - * $isStart = Common::getRequestVar('isStart', 1, 'int'); - * Http::downloadChunk("http://bigfiles.com/averybigfile.zip", $outputPath, $isStart == 1); - * } - * ``` + * ``` + * // PHP controller action + * public function myAction() + * { + * $outputPath = PIWIK_INCLUDE_PATH . '/tmp/averybigfile.zip'; + * $isStart = Common::getRequestVar('isStart', 1, 'int'); + * Http::downloadChunk("http://bigfiles.com/averybigfile.zip", $outputPath, $isStart == 1); + * } + * ``` * * @param string $url The url to download from. * @param string $outputPath The path to the file to save/append to. - * @param bool $isContinuation True if this is the continuation of a download, + * @param bool $isContinuation `true` if this is the continuation of a download, * or if we're starting a fresh one. * @throws Exception if the file already exists and we're starting a new download, * if we're trying to continue a download that never started @@ -708,7 +712,7 @@ class Http * @param int $timeout The amount of seconds to wait before aborting the HTTP request. * @throws Exception if the response cannot be saved to `$destinationPath`, if the HTTP response cannot be sent, * if there are more than 5 redirects or if the request times out. - * @return bool true on success, throws Exception on failure + * @return bool `true` on success, throws Exception on failure * @api */ public static function fetchRemoteFile($url, $destinationPath = null, $tries = 0, $timeout = 10) diff --git a/core/Log.php b/core/Log.php index b2facc6cb6..69856c44a8 100644 --- a/core/Log.php +++ b/core/Log.php @@ -25,14 +25,15 @@ use Piwik\Db; * screen writer. * * Currently, Piwik supports the following logging backends: - * - logging to the screen - * - logging to a file - * - logging to a database + * + * - **screen**: logging to the screen + * - **file**: logging to a file + * - **database**: logging to Piwik's MySQL database * * ### Logging configuration * * The logging utility can be configured by manipulating the INI config options in the - * [log] section. + * `[log]` section. * * The following configuration options can be set: * @@ -56,13 +57,18 @@ use Piwik\Db; * ### Custom message formatting * * If you'd like to format log messages differently for different backends, you can use - * one of the `'Log.format...Message'` events. These events are fired when an object is - * logged. You can create your own custom class containing the information to log and - * listen to this event. + * one of the `'Log.format...Message'` events. + * + * These events are fired when an object is logged. You can create your own custom class + * containing the information to log and listen to these events to format it correctly for + * different backends. + * + * If you don't care about the backend when formatting an object, implement a `__toString()` + * in the custom class. * * ### Custom log writers * - * New logging backends can be added via the `'Log.getAvailableWriters'` event. A log + * New logging backends can be added via the {@hook Log.getAvailableWriters}` event. A log * writer is just a callback that accepts log entry information (such as the message, * level, etc.), so any backend could conceivably be used (including existing PSR3 * backends). @@ -75,6 +81,25 @@ use Piwik\Db; * Log::verbose("This log message uses %s params, but %s will only be called if the" * . " configured log level includes %s.", "sprintf", "sprintf", "verbose"); * + * **Logging objects** + * + * class MyDebugInfo + * { + * // ... + * + * public function __toString() + * { + * return // ... + * } + * } + * + * try { + * $myThirdPartyServiceClient->doSomething(); + * } catch (Exception $unexpectedError) { + * $debugInfo = new MyDebugInfo($unexpectedError, $myThirdPartyServiceClient); + * Log::debug($debugInfo); + * } + * * @method static \Piwik\Log getInstance() */ class Log extends Singleton @@ -155,8 +180,8 @@ class Log extends Singleton /** * Logs a message using the ERROR log level. * - * Note: Messages logged with the ERROR level are always logged to the screen in addition - * to configured writers. + * _Note: Messages logged with the ERROR level are always logged to the screen in addition + * to configured writers._ * * @param string $message The log message. This can be a sprintf format string. * @param ... mixed Optional sprintf params. @@ -217,11 +242,11 @@ class Log extends Singleton /** * Creates log message combining logging info including a log level, tag name, - * date time, and caller provided log message. The log message can be set through - * the string_message_format ini option in the [log] section. By default it will + * date time, and caller-provided log message. The log message can be set through + * the `[log] string_message_format` INI config option. By default it will * create log messages like: * - * [tag:datetime] log message + * **LEVEL [tag:datetime] log message** * * @param int $level * @param string $tag diff --git a/core/Menu/MenuAbstract.php b/core/Menu/MenuAbstract.php index e5293d5733..0662cb20aa 100644 --- a/core/Menu/MenuAbstract.php +++ b/core/Menu/MenuAbstract.php @@ -18,7 +18,7 @@ use Piwik\Singleton; * Base class for classes that manage one of Piwik's menus. * * There are three menus in Piwik, the main menu, the top menu and the admin menu. - * Each menu has a class that manages the rendering of it. Each class invokes + * Each menu has a class that manages the menu's content. Each class invokes * a different event to allow plugins to add new menu items. * * @package Piwik_Menu diff --git a/core/Metrics.php b/core/Metrics.php index 9a4071658a..8ceaa29752 100644 --- a/core/Metrics.php +++ b/core/Metrics.php @@ -18,7 +18,7 @@ require_once PIWIK_INCLUDE_PATH . "/core/Piwik.php"; * related helper functions. * * Of note are the `INDEX_...` constants. In the database, metric column names - * are stored in DataTable rows are stored as integers to save space. The integer + * in {@link DataTable} rows are stored as integers to save space. The integer * values used are determined by these constants. * * @api diff --git a/core/MetricsFormatter.php b/core/MetricsFormatter.php index 61f1926c06..5fd464ff8d 100644 --- a/core/MetricsFormatter.php +++ b/core/MetricsFormatter.php @@ -22,7 +22,8 @@ class MetricsFormatter { /** * Returns a prettified string representation of a number. The result will have - * thousands separators and a decimal point specific to the current locale. + * thousands separators and a decimal point specific to the current locale, eg, + * `'1,000,000.05'` or `'1.000.000,05'`. * * @param number $value * @return string diff --git a/core/Notification/Manager.php b/core/Notification/Manager.php index 879227ce5a..42452937fa 100644 --- a/core/Notification/Manager.php +++ b/core/Notification/Manager.php @@ -27,7 +27,7 @@ class Manager private static $session = null; /** - * Posts a notification that will be shown in Piwik's status bar. If a notification with the same id + * Posts a notification that will be shown in Piwik's status bar. If a notification with the same ID * has been posted and has not been closed/removed, it will be replaced with `$notification`. * * @param string $id A unique identifier for this notification. The ID must be a valid HTML @@ -44,8 +44,9 @@ class Manager } /** - * Cancel a previously registered (or persistent) notification. - * @param $id + * Removes a posted notification by ID. + * + * @param $id The notification ID, see {@link notify()}. */ public static function cancel($id) { @@ -55,8 +56,10 @@ class Manager } /** - * Cancels all previously registered non-persist notification. Call this method after the notifications have been - * displayed to make sure all non-persistent notifications won't be displayed multiple times. + * Removes all temporary notifications. + * + * Call this method after the notifications have been + * displayed to make sure temporary notifications won't be displayed twice. */ public static function cancelAllNonPersistent() { diff --git a/core/Period/Range.php b/core/Period/Range.php index 722de00c83..91cf5de435 100644 --- a/core/Period/Range.php +++ b/core/Period/Range.php @@ -25,7 +25,7 @@ use Piwik\Piwik; * date=2007-07-24,2013-11-15). * * The range period differs from other periods mainly in that since it is arbitrary, - * range periods are not archived by the archive.php cron script. + * range periods are not pre-archived by the **archive.php** cron script. * * @package Piwik * @subpackage Period @@ -86,7 +86,7 @@ class Range extends Period } /** - * Returns the start date of the period + * Returns the start date of the period. * * @return Date * @throws Exception @@ -101,7 +101,7 @@ class Range extends Period } /** - * Returns the current period as a string + * Returns the current period as a string. * * @return string */ @@ -134,7 +134,7 @@ class Range extends Period } /** - * Sets the default end date of the period + * Sets the default end date of the period. * * @param Date $oDate */ @@ -218,11 +218,11 @@ class Range extends Period } /** - * Given a date string, returns false if not a date range, - * or returns the array containing date start, date end + * Given a date string, returns `false` if not a date range, + * or returns the array containing start and end dates. * * @param string $dateString - * @return mixed array(1 => dateStartString, 2 => dateEndString ) or false if the input was not a date range + * @return mixed array(1 => dateStartString, 2 => dateEndString) or `false` if the input was not a date range. */ static public function parseDateRange($dateString) { @@ -236,7 +236,7 @@ class Range extends Period protected $endDate = null; /** - * Returns the end date of the period + * Returns the end date of the period. * * @return null|Date */ @@ -249,7 +249,7 @@ class Range extends Period } /** - * Determine which kind of period is best to use + * Determine which kind of period is best to use. * See Range.test.php * * @param Date $startDate @@ -400,7 +400,7 @@ class Range extends Period } /** - * Returns a date ragne string given a period type, end date and number of periods + * Returns a date range string given a period type, end date and number of periods * the range spans over. * * @param string $period The sub period type, `'day'`, `'week'`, `'month'` and `'year'`. diff --git a/core/Piwik.php b/core/Piwik.php index 840f29b428..e6b8f190cd 100644 --- a/core/Piwik.php +++ b/core/Piwik.php @@ -31,7 +31,7 @@ require_once PIWIK_INCLUDE_PATH . '/core/Translate.php'; * Main piwik helper class. * * Contains helper methods for a variety of common tasks. Plugin developers are - * encouraged to reuse these methods. + * encouraged to reuse these methods as much as possible. * * @package Piwik */ @@ -49,10 +49,18 @@ class Piwik 'range' => 5, ); - /** The idGoal query parameter value for the special 'abandoned carts' goal. */ + /** + * The idGoal query parameter value for the special 'abandoned carts' goal. + * + * @api + */ const LABEL_ID_GOAL_IS_ECOMMERCE_CART = 'ecommerceAbandonedCart'; - /** The idGoal query parameter value for the special 'ecommerce' goal. */ + /** + * The idGoal query parameter value for the special 'ecommerce' goal. + * + * @api + */ const LABEL_ID_GOAL_IS_ECOMMERCE_ORDER = 'ecommerceOrder'; /** @@ -259,7 +267,7 @@ class Piwik } /** - * Returns true if the current user is either the super user or the user specified by + * Returns `true` if the current user is either the super user or the user specified by * `$theUser`. * * @param string $theUser A username. @@ -312,7 +320,7 @@ class Piwik } /** - * Returns true if the current user is the special anonymous user or not. + * Returns true if the current user is the special **anonymous** user or not. * * @return bool * @api @@ -358,7 +366,7 @@ class Piwik } /** - * Returns true if the user has admin access to the requested sites, false if otherwise. + * Returns `true` if the user has admin access to the requested sites, `false` if otherwise. * * @param int|array $idSites The list of site IDs to check access for. * @return bool @@ -377,7 +385,7 @@ class Piwik /** * Checks that the current user has admin access to the requested list of sites. * - * @param int|array $idSites The list of site IDs to check access for. + * @param int|array $idSites One or more site IDs to check access for. * @throws Exception If user doesn't have admin access. * @api */ @@ -387,7 +395,7 @@ class Piwik } /** - * Returns true if the current user has admin access to at least one site. + * Returns `true` if the current user has admin access to at least one site. * * @return bool * @api @@ -414,9 +422,9 @@ class Piwik } /** - * Returns true if the user has view access to the requested list of sites. + * Returns `true` if the user has view access to the requested list of sites. * - * @param int|array $idSites The list of site IDs to check access for. + * @param int|array $idSites One or more site IDs to check access for. * @return bool * @api */ @@ -443,7 +451,7 @@ class Piwik } /** - * Returns true if the current user has view access to at least one site. + * Returns `true` if the current user has view access to at least one site. * * @return bool * @api @@ -559,7 +567,7 @@ class Piwik */ /** - * Returns true if the email address is a valid. + * Returns `true` if supplied the email address is a valid. * * @param string $emailAddress * @return bool @@ -571,8 +579,9 @@ class Piwik } /** - * Returns true if the login is valid. - * Warning: does not check if the login already exists! You must use UsersManager_API->userExists as well. + * Returns `true` if the login is valid. + * + * _Warning: does not check if the login already exists! You must use UsersManager_API->userExists as well._ * * @param string $userLogin * @throws Exception @@ -676,7 +685,6 @@ class Piwik * have their observers for this event executed. * @param array|null $plugins The list of plugins to execute observers for. If null, all * plugin observers will be executed. - * @return void * @api */ public static function postEvent($eventName, $params = array(), $pending = false, $plugins = null) @@ -687,8 +695,8 @@ class Piwik /** * Register an observer to an event. * - * Observers should normally be defined in plugin objects. It is unlikely that you will - * need to use this function. + * **_Note: Observers should normally be defined in plugin objects. It is unlikely that you will + * need to use this function._** * * @param string $eventName The event name. * @param callable|array $function The observer. @@ -711,13 +719,13 @@ class Piwik } /** - * Returns an internationalized string using a translation ID. If a translation - * cannot be found for the ID, the ID is returned. + * Returns an internationalized string using a translation token. If a translation + * cannot be found for the toke, the token is returned. * * @param string $translationId Translation ID, eg, `'General_Date'`. * @param array|string|int $args `sprintf` arguments to be applied to the internationalized * string. - * @return string + * @return string The translated string or `$translationId`. * @api */ public static function translate($translationId, $args = array()) diff --git a/core/Plugin.php b/core/Plugin.php index 908bdad518..53fe0f8559 100644 --- a/core/Plugin.php +++ b/core/Plugin.php @@ -25,8 +25,8 @@ require_once PIWIK_INCLUDE_PATH . '/core/Plugin/MetadataLoader.php'; * Plugins that can specify everything they need to in the _plugin.json_ files, * such as themes, don't need to implement this class. * - * The name of the implementation of this class should be the same name as the - * plugin they are a part of (eg, `class UserCountry extends Plugin`). + * Class implementations should be named after the plugin they are a part of + * (eg, `class UserCountry extends Plugin`). * * ### Plugin Metadata * @@ -60,10 +60,10 @@ require_once PIWIK_INCLUDE_PATH . '/core/Plugin/MetadataLoader.php'; * public function getListHooksRegistered() * { * return array( - * 'API.getReportMetadata' => 'myPluginFunction', + * 'API.getReportMetadata' => 'getReportMetadata', * 'Another.event' => array( * 'function' => 'myOtherPluginFunction', - * 'after' => true // execute after callbacks w/o ordering + * 'after' => true // executes this callback after others * ) * ); * } @@ -77,6 +77,16 @@ require_once PIWIK_INCLUDE_PATH . '/core/Plugin/MetadataLoader.php'; * { * Db::exec("DROP TABLE IF EXISTS " . Common::prefixTable('mytable')); * } + * + * public function getReportMetadata(&$metadata) + * { + * // ... + * } + * + * public function myOtherPluginFunction() + * { + * // ... + * } * } * * @package Piwik @@ -104,7 +114,7 @@ class Plugin * @param string|bool $pluginName A plugin name to force. If not supplied, it is set * to the last part of the class name. * @throws \Exception If plugin metadata is defined in both the getInformation() method - * and the plugin.json file. + * and the **plugin.json** file. */ public function __construct($pluginName = false) { @@ -139,7 +149,8 @@ class Plugin } /** - * Returns the plugin details + * Returns plugin information, including: + * * - 'description' => string // 1-2 sentence description of the plugin * - 'author' => string // plugin author * - 'author_homepage' => string // author homepage URL (or email "mailto:youremail@example.org") @@ -159,8 +170,12 @@ class Plugin /** * Returns a list of hooks with associated event observers. + * + * Derived classes should use this method to associate callbacks with events. * - * @return array eg, array( + * @return array eg, + * + * array( * 'API.getReportMetadata' => 'myPluginFunction', * 'Another.event' => array( * 'function' => 'myOtherPluginFunction', @@ -179,7 +194,7 @@ class Plugin /** * This method is executed after a plugin is loaded and translations are registered. - * Useful for initialization code that uses translated strings from the plugin. + * Useful for initialization code that uses translated strings. */ public function postLoad() { @@ -189,6 +204,7 @@ class Plugin /** * Installs the plugin. Derived classes should implement this class if the plugin * needs to: + * * - create tables * - update existing tables * - etc. @@ -201,8 +217,8 @@ class Plugin } /** - * Uninstalls the plugins. Derived classes should implement this class if the changes - * made in {@link install()} should be undone during uninstallation. + * Uninstalls the plugins. Derived classes should implement this method if the changes + * made in {@link install()} need to be undone during uninstallation. * * In most cases, if you have an {@link install()} method, you should provide * an {@link uninstall()} method. @@ -242,7 +258,7 @@ class Plugin } /** - * Returns true if this plugin is a theme, false if otherwise. + * Returns `true` if this plugin is a theme, `false` if otherwise. * * @return bool */ @@ -254,7 +270,7 @@ class Plugin /** * Returns the plugin's base class name without the namespace, - * e.g., "UserCountry" when the plugin class is "Piwik\Plugins\UserCountry\UserCountry". + * e.g., `"UserCountry"` when the plugin class is `"Piwik\Plugins\UserCountry\UserCountry"`. * * @return string */ @@ -264,9 +280,10 @@ class Plugin } /** - * Extracts the plugin name from a backtrace array. Returns false if we can't find one. + * Extracts the plugin name from a backtrace array. Returns `false` if we can't find one. * - * @param array $backtrace The result of the debug_backtrace() or Exception::getTrace(). + * @param array $backtrace The result of {@link debug_backtrace()} or + * [Exception::getTrace()](http://www.php.net/manual/en/exception.gettrace.php). * @return string|false */ public static function getPluginNameFromBacktrace($backtrace) diff --git a/core/RankingQuery.php b/core/RankingQuery.php index 375d73b599..7691d98d3c 100644 --- a/core/RankingQuery.php +++ b/core/RankingQuery.php @@ -15,9 +15,9 @@ use Exception; /** * The ranking query class wraps an arbitrary SQL query with more SQL that limits - * the number of results while grouping the rest to "Others" and allows for some - * more fancy things that can be configured via method calls of this class. The - * advanced use cases are explained in the doc comments of the methods. + * the number of results while aggregating the rest in an a new "Others" row. It als + * allows for some more fancy things that can be configured via method calls of this + * class. The advanced use cases are explained in the doc comments of the methods. * * The general use case looks like this: * diff --git a/core/ScheduledTime.php b/core/ScheduledTime.php index 47aaa968a8..e7743fa6a0 100644 --- a/core/ScheduledTime.php +++ b/core/ScheduledTime.php @@ -94,8 +94,10 @@ abstract class ScheduledTime abstract public function getRescheduledTime(); /** + * Sets the day of the period to execute the scheduled task. Not a valid operation for all period types. + * * @abstract - * @param int $_day the day to set + * @param int $_day a number describing the day to set. Its meaning depends on the ScheduledTime's period type. * @throws Exception if method not supported by subclass or parameter _day is invalid */ abstract public function setDay($_day); diff --git a/core/Segment.php b/core/Segment.php index db7cc49970..c4de27ab9f 100644 --- a/core/Segment.php +++ b/core/Segment.php @@ -20,8 +20,8 @@ use Piwik\Plugins\API\API; * select visits that have a specific browser or come from a specific * country, or both. * - * Individual segment parameters (such as `browserCode` and `countryCode`) - * are defined by individual plugins. Read about the {@hook API.getSegmentDimensionMetadata} + * Individual segment dimensions (such as `browserCode` and `countryCode`) + * are defined by plugins. Read about the {@hook API.getSegmentDimensionMetadata} * event to learn more. * * Plugins that aggregate data stored in Piwik can support segments by @@ -46,7 +46,7 @@ use Piwik\Plugins\API\API; * * Db::fetchAll($query['sql'], $query['bind']); * - * **Creating a 'null' segment** + * **Creating a _null_ segment** * * $idSites = array(1,2,3); * $segment = new Segment('', $idSites); @@ -124,7 +124,7 @@ class Segment } /** - * Returns true if the segment is empty, false if otherwise. + * Returns `true` if the segment is empty, `false` if otherwise. */ public function isEmpty() { diff --git a/core/Singleton.php b/core/Singleton.php index a32a8d045a..a121789dea 100644 --- a/core/Singleton.php +++ b/core/Singleton.php @@ -12,7 +12,7 @@ namespace Piwik; /** - * The singleton class restricts the instantiation of a class to one object only. + * The singleton base class restricts the instantiation of derived classes to one object only. * * All plugin APIs are singletons and thus extend this class. * diff --git a/core/Site.php b/core/Site.php index 6e4e9c4753..f3b49102f6 100644 --- a/core/Site.php +++ b/core/Site.php @@ -15,7 +15,17 @@ use Exception; use Piwik\Plugins\SitesManager\API; /** - * Provides access to individual site data (such as name, URL, etc.). + * Provides access to individual [site entity](/guides/persistence-and-the-mysql-backend#websites-aka-sites) data + * (including name, URL, etc.). + * + * **Data Cache** + * + * Site data can be cached in order to avoid performing too many queries. + * If a method needs many site entities, it is more efficient to query all of what + * you need beforehand via the **SitesManager** API, then cache it using {@link setSites()} or + * {@link setSitesFromArray()}. + * + * Subsequent calls to `new Site($id)` will use the data in the cache instead of querying the database. * * ### Examples * @@ -64,10 +74,9 @@ class Site * individual site data. * * @param array $sites The array of sites data. Indexed by site ID. eg, - * ``` - * array('1' => array('name' => 'Site 1', ...), - * '2' => array('name' => 'Site 2', ...))` - * ``` + * + * array('1' => array('name' => 'Site 1', ...), + * '2' => array('name' => 'Site 2', ...))` */ public static function setSites($sites) { @@ -117,12 +126,11 @@ class Site * Sets the cached Site data with a non-associated array of site data. * * @param array $sites The array of sites data. eg, - * ``` - * array( - * array('idsite' => '1', 'name' => 'Site 1', ...), - * array('idsite' => '2', 'name' => 'Site 2', ...), - * ) - * ``` + * + * array( + * array('idsite' => '1', 'name' => 'Site 1', ...), + * array('idsite' => '2', 'name' => 'Site 2', ...), + * ) */ public static function setSitesFromArray($sites) { @@ -137,6 +145,7 @@ class Site * @param array $siteIds Array of IDs for each site being displayed. * @return Date[] of two Date instances. First is the min-date & the second * is the max date. + * @ignore */ public static function getMinMaxDateAcrossWebsites($siteIds) { @@ -231,7 +240,8 @@ class Site } /** - * Returns the type of the website (by default "website") + * Returns the website type (by default `"website"`, which means it is a single website). + * * @return string */ public function getType() @@ -341,10 +351,11 @@ class Site } /** - * Checks the given string for valid site ids and returns them as an array. + * Checks the given string for valid site IDs and returns them as an array. * - * @param string $ids Comma separated idSite list, eg, `'1,2,3,4'`. - * @param bool|string $_restrictSitesToLogin Used only when running as a scheduled task. + * @param string|array $ids Comma separated idSite list, eg, `'1,2,3,4'` or an array of IDs, eg, + * `array(1, 2, 3, 4)`. + * @param bool|string $_restrictSitesToLogin Implementation detail. Used only when running as a scheduled task. * @return array An array of valid, unique integers. */ static public function getIdSitesFromIdSitesString($ids, $_restrictSitesToLogin = false) @@ -414,6 +425,9 @@ class Site return self::$infoSites; } + /** + * @ignore + */ static public function getSite($id) { return self::getFor($id); @@ -475,7 +489,7 @@ class Site } /** - * Returns whether the site with the specified ID is ecommerce enabled + * Returns whether the site with the specified ID is ecommerce enabled or not. * * @param int $idsite The site ID. * @return string @@ -486,7 +500,7 @@ class Site } /** - * Returns whether the site with the specified ID is Site Search enabled + * Returns whether the site with the specified ID is Site Search enabled. * * @param int $idsite The site ID. * @return string diff --git a/core/Tracker.php b/core/Tracker.php index 0761eafd46..2b75a65a0f 100644 --- a/core/Tracker.php +++ b/core/Tracker.php @@ -588,8 +588,8 @@ class Tracker $visit = null; /** - * Triggered before a new **visit object** is created. Subscribers to this - * event can force the use of a custom visit object that extends from + * Triggered before a new **visit tracking object** is created. Subscribers to this + * event can force the use of a custom visit tracking object that extends from * {@link Piwik\Tracker\VisitInterface}. * * @param \Piwik\Tracker\VisitInterface &$visit Initialized to null, but can be set to diff --git a/core/Tracker/VisitInterface.php b/core/Tracker/VisitInterface.php index f736a0c663..1f5bfe46ad 100644 --- a/core/Tracker/VisitInterface.php +++ b/core/Tracker/VisitInterface.php @@ -12,19 +12,24 @@ namespace Piwik\Tracker; /** + * Interface implemented by classes that track visit information for the Tracker. + * * @package Piwik * @subpackage Tracker - * @api */ interface VisitInterface { /** + * Stores the object describing the current tracking request. + * * @param Request $request * @return void */ public function setRequest(Request $request); /** + * Tracks a visit. + * * @return void */ public function handle(); diff --git a/core/Url.php b/core/Url.php index 5ab521978f..090bd1542e 100644 --- a/core/Url.php +++ b/core/Url.php @@ -24,23 +24,29 @@ use Exception; * * **Redirect to a different controller action** * - * $url = Url::getCurrentQueryStringWithParametersModified(array( - * 'module' => 'UserSettings', - * 'action' => 'index' - * )); - * Url::redirectToUrl($url); + * public function myControllerAction() + * { + * $url = Url::getCurrentQueryStringWithParametersModified(array( + * 'module' => 'UserSettings', + * 'action' => 'index' + * )); + * Url::redirectToUrl($url); + * } * * **Link to a different controller action in a template** * - * $url = Url::getCurrentQueryStringWithParametersModified(array( - * 'module' => 'UserCountryMap', - * 'action' => 'realtimeMap', - * 'changeVisitAlpha' => 0, - * 'removeOldVisits' => 0 - * )); - * $view = new View("@MyPlugin/myPopup"); - * $view->realtimeMapUrl = $url; - * echo $view->render(); + * public function myControllerAction() + * { + * $url = Url::getCurrentQueryStringWithParametersModified(array( + * 'module' => 'UserCountryMap', + * 'action' => 'realtimeMap', + * 'changeVisitAlpha' => 0, + * 'removeOldVisits' => 0 + * )); + * $view = new View("@MyPlugin/myPopup"); + * $view->realtimeMapUrl = $url; + * return $view->render(); + * } * * @package Piwik */ @@ -69,7 +75,7 @@ class Url * Returns the current URL without the query string. * * @param bool $checkTrustedHost Whether to do trusted host check. Should ALWAYS be true, - * except in Controller. + * except in {@link Piwik\Plugin\Controller}. * @return string eg, `"http://example.org/dir1/dir2/index.php"` if the current URL is * `"http://example.org/dir1/dir2/index.php?param1=value1¶m2=value2"`. * @api @@ -192,11 +198,12 @@ class Url } /** - * Validates the "Host" header (untrusted user input). + * Validates the **Host** HTTP header (untrusted user input). Used to prevent Host header + * attacks. * - * @param string|bool $host Contents of Host: header from Request. If false, gets the + * @param string|bool $host Contents of Host: header from the HTTP request. If `false`, gets the * value from the request. - * @return bool True if valid; false otherwise. + * @return bool `true` if valid; `false` otherwise. */ static public function isValidHost($host = false) { @@ -360,12 +367,11 @@ class Url * * @return array If current URL is `"http://example.org/dir1/dir2/index.php?param1=value1¶m2=value2"` * this will return: - * ``` - * array( - * 'param1' => string 'value1', - * 'param2' => string 'value2' - * ) - * ``` + * + * array( + * 'param1' => string 'value1', + * 'param2' => string 'value2' + * ) * @api */ static public function getArrayFromCurrentQueryString() @@ -400,7 +406,7 @@ class Url } /** - * Converts an an array of parameters name => value mappings to a query + * Converts an array of parameters name => value mappings to a query * string. * * @param array $parameters eg. `array('param1' => 10, 'param2' => array(1,2))` @@ -460,7 +466,7 @@ class Url } /** - * Returns the HTTP_REFERER header, or false if not found. + * Returns the **HTTP_REFERER** `$_SERVER` variable, or `false` if not found. * * @return string|false * @api @@ -474,7 +480,7 @@ class Url } /** - * Returns true if the URL points to something on the same host, false if otherwise. + * Returns `true` if the URL points to something on the same host, `false` if otherwise. * * @param string $url * @return bool True if local; false otherwise. diff --git a/core/View.php b/core/View.php index e027f3bd1f..105434e00a 100644 --- a/core/View.php +++ b/core/View.php @@ -30,8 +30,8 @@ if (!defined('PIWIK_USER_PATH')) { * View will also set several properties that will be available in all Twig * templates, including: * - * - **currentModule**: The value of the 'module' query parameter. - * - **currentAction**: The value of the 'action' query parameter. + * - **currentModule**: The value of the **module** query parameter. + * - **currentAction**: The value of the **action** query parameter. * - **userLogin**: The current user login name. * - **sites**: List of site data for every site the current user has at least * view access for. @@ -46,6 +46,13 @@ if (!defined('PIWIK_USER_PATH')) { * - **loginModule**: The name of the currently used authentication module. * - **userAlias**: The alias of the current user. * + * ### Template Naming Convention + * + * Template files should be named after the controller method they are used in. + * If they are used in more than one controller method or are included by another + * template, they should describe the output they generate and be prefixed with + * an underscore, eg, **_dataTable.twig**. + * * ### Twig * * Twig templates must exist in the **templates** folder in a plugin's root @@ -58,9 +65,9 @@ if (!defined('PIWIK_USER_PATH')) { * to the filter. * - **urlRewriteWithParameters**: Modifies the current query string with the given * set of parameters, eg, - * ``` - * {{ {'module':'MyPlugin', 'action':'index'} | urlRewriteWithParameters }} - * ``` + * + * {{ {'module':'MyPlugin', 'action':'index'} | urlRewriteWithParameters }} + * * - **sumTime**: Pretty formats an number of seconds. * - **money**: Formats a numerical value as a monetary value using the currency * of the supplied site (second arg is site ID). @@ -85,10 +92,14 @@ if (!defined('PIWIK_USER_PATH')) { * * **Basic usage** * - * $view = new View("@MyPlugin/myView"); - * $view->property1 = "a view property"; - * $view->property2 = "another view property"; - * echo $view->render(); + * // a controller method + * public function myView() + * { + * $view = new View("@MyPlugin/myView"); + * $view->property1 = "a view property"; + * $view->property2 = "another view property"; + * return $view->render(); + * } * * @package Piwik * @@ -284,8 +295,8 @@ class View implements ViewInterface * Set X-Frame-Options field in the HTTP response. The header is set just * before rendering. * - * Note: setting this allows you to make sure the View **cannot** be - * embedded in iframes. Learn more [here](https://developer.mozilla.org/en-US/docs/HTTP/X-Frame-Options). + * _Note: setting this allows you to make sure the View **cannot** be + * embedded in iframes. Learn more [here](https://developer.mozilla.org/en-US/docs/HTTP/X-Frame-Options)._ * * @param string $option ('deny' or 'sameorigin') */ @@ -343,6 +354,9 @@ class View implements ViewInterface /** * Creates a View for and then renders the single report template. + * + * Can be used for pages that display only one report to avoid having to create + * a new template. * * @param string $title The report title. * @param string $reportHtml The report body HTML. diff --git a/core/View/ViewInterface.php b/core/View/ViewInterface.php index 2a0fb6c0c6..1eaeb2e27d 100644 --- a/core/View/ViewInterface.php +++ b/core/View/ViewInterface.php @@ -20,9 +20,9 @@ namespace Piwik\View; interface ViewInterface { /** - * Outputs data. + * Returns data. * - * @return mixed (image, array, html...) + * @return string Serialized data, eg, (image, array, html...). */ function render(); }
\ No newline at end of file diff --git a/core/ViewDataTable/Factory.php b/core/ViewDataTable/Factory.php index 4dd4a15273..e657d0a797 100644 --- a/core/ViewDataTable/Factory.php +++ b/core/ViewDataTable/Factory.php @@ -73,7 +73,7 @@ class Factory * Creates a {@link Piwik\Plugin\ViewDataTable} instance by ID. If the **viewDataTable** query parameter is set, * this parameter's value is used as the ID. * - * See [ViewDataTable docs](#) to read about the ViewDataTable implementations that are packaged with Piwik. + * See {@link Piwik\Plugin\ViewDataTable} to read about the visualizations that are packaged with Piwik. * * @param string|null $defaultType A ViewDataTable ID representing the default ViewDataTable type to use. If * the **viewDataTable** query parameter is not found, this value is used as diff --git a/core/ViewDataTable/RequestConfig.php b/core/ViewDataTable/RequestConfig.php index bc0311f678..733511dc06 100644 --- a/core/ViewDataTable/RequestConfig.php +++ b/core/ViewDataTable/RequestConfig.php @@ -196,7 +196,7 @@ class RequestConfig /** * Whether to run ViewDataTable's list of queued filters or not. * - * NOTE: Priority queued filters are always run. + * _NOTE: Priority queued filters are always run._ * * Default value: false */ @@ -216,6 +216,12 @@ class RequestConfig return get_object_vars($this); } + /** + * Marks request properties as client side properties. [Read this](#client-side-properties-desc) + * to learn more. + * + * @param array $propertyNames List of property names, eg, `array('disable_queued_filters', 'filter_column')`. + */ public function addPropertiesThatShouldBeAvailableClientSide(array $propertyNames) { foreach ($propertyNames as $propertyName) { @@ -223,6 +229,12 @@ class RequestConfig } } + /** + * Marks display properties as overridable. [Read this](#overridable-properties-desc) to + * learn more. + * + * @param array $propertyNames List of property names, eg, `array('disable_queued_filters', 'filter_column')`. + */ public function addPropertiesThatCanBeOverwrittenByQueryParams(array $propertyNames) { foreach ($propertyNames as $propertyName) { @@ -243,7 +255,7 @@ class RequestConfig } /** - * Returns true if queued filters have been disabled, false if otherwise. + * Returns `true` if queued filters have been disabled, `false` if otherwise. * * @return bool */ @@ -253,7 +265,7 @@ class RequestConfig } /** - * Returns true if generic filters have been disabled, false if otherwise. + * Returns `true` if generic filters have been disabled, `false` if otherwise. * * @return bool */ |