refs #4194 marked some classes/methods/functions as available for plugins

32 files changed, 112 insertions, 2 deletions

diff --git a/core/API/Request.php b/core/API/Request.php
index 5e9ba6d850..2d41682b7d 100644
--- a/core/API/Request.php
+++ b/core/API/Request.php
@@ -45,6 +45,8 @@ use Piwik\UrlHelper;
  * @see http://piwik.org/docs/analytics-api
  * @package Piwik
  * @subpackage Piwik_API
+ *
+ * @api
  */
 class Request
 {
diff --git a/core/Archive.php b/core/Archive.php
index fad9666809..543840ec02 100644
--- a/core/Archive.php
+++ b/core/Archive.php
@@ -47,6 +47,8 @@ use Piwik\DataAccess\ArchiveSelector;
  *
  * @package Piwik
  * @subpackage Archive
+ *
+ * @api
  */
 class Archive
 {
diff --git a/core/ArchiveProcessor/Day.php b/core/ArchiveProcessor/Day.php
index b59069756f..769274d4cf 100644
--- a/core/ArchiveProcessor/Day.php
+++ b/core/ArchiveProcessor/Day.php
@@ -18,6 +18,8 @@ use Piwik\DataTable;
  * This class
  * @package Piwik
  * @subpackage ArchiveProcessor
+ *
+ * @api
  */
 class Day extends ArchiveProcessor
 {
diff --git a/core/ArchiveProcessor/Period.php b/core/ArchiveProcessor/Period.php
index b621cf401a..6807d01346 100644
--- a/core/ArchiveProcessor/Period.php
+++ b/core/ArchiveProcessor/Period.php
@@ -29,6 +29,8 @@ use Piwik\SettingsPiwik;
  *
  * @package Piwik
  * @subpackage ArchiveProcessor
+ *
+ * @api
  */
 class Period extends ArchiveProcessor
 {
diff --git a/core/CacheFile.php b/core/CacheFile.php
index 9d6faf64dc..833daaff1e 100644
--- a/core/CacheFile.php
+++ b/core/CacheFile.php
@@ -21,6 +21,7 @@ use Exception;
  * - openx/lib/max/Delivery/cache.php
  *
  * @package Piwik
+ * @api
  */
 class CacheFile
 {
diff --git a/core/Common.php b/core/Common.php
index 622dc9df40..806278b2a7 100644
--- a/core/Common.php
+++ b/core/Common.php
@@ -64,6 +64,7 @@ class Common
      *
      * @param string $table  The table name to prefix, ie "log_visit"
      * @return string  The table name prefixed, ie "piwik-production_log_visit"
+     * @api
      */
     public static function prefixTable($table)
     {
@@ -91,6 +92,7 @@ class Common
      *
      * @param string $table
      * @return string
+     * @api
      */
     public static function unprefixTable($table)
     {
@@ -374,6 +376,7 @@ class Common
      *                    or if the variable we want to read doesn't have neither a value nor a default value specified
      *
      * @return mixed The variable after cleaning
+     * @api
      */
     public static function getRequestVar($varName, $varDefault = null, $varType = null, $requestArrayToUse = null)
     {
@@ -573,6 +576,7 @@ class Common
      *
      * @param mixed $value
      * @return string
+     * @api
      */
     public static function json_encode($value)
     {
@@ -586,6 +590,7 @@ class Common
      * @param string $json
      * @param bool $assoc
      * @return mixed
+     * @api
      */
     public static function json_decode($json, $assoc = false)
     {
@@ -638,6 +643,7 @@ class Common
      * @see core/DataFiles/Languages.php
      *
      * @return array  Array of 2 letter ISO codes => Language name (in English)
+     * @api
      */
     public static function getLanguagesList()
     {
@@ -653,6 +659,7 @@ class Common
      * @see core/DataFiles/LanguageToCountry.php
      *
      * @return array  Array of ( 2 letter ISO language codes => 2 letter ISO country codes )
+     * @api
      */
     public static function getLanguageToCountryList()
     {
diff --git a/core/Config.php b/core/Config.php
index 2d64797ac7..892646e84c 100644
--- a/core/Config.php
+++ b/core/Config.php
@@ -51,6 +51,7 @@ class Config
      * Returns the singleton Piwik_Config
      *
      * @return \Piwik\Config
+     * @api
      */
     public static function getInstance()
     {
@@ -291,6 +292,7 @@ class Config
      * @param string $name
      * @return string|array The value requested, returned by reference
      * @throws Exception if the value requested not found in both files
+     * @api
      */
     public function &__get($name)
     {
@@ -341,6 +343,7 @@ class Config
      *
      * @param string $name This corresponds to the section name
      * @param mixed $value
+     * @api
      */
     public function __set($name, $value)
     {
@@ -514,6 +517,7 @@ class Config
 
     /**
      * Force save
+     * @api
      */
     public function forceSave()
     {
diff --git a/core/Console/Command.php b/core/Console/Command.php
index 920d69c303..b386525b84 100644
--- a/core/Console/Command.php
+++ b/core/Console/Command.php
@@ -14,6 +14,10 @@ use Piwik\Common;
 use Symfony\Component\Console\Command\Command as SymfonyCommand;
 use Symfony\Component\Console\Output\OutputInterface;
 
+/**
+ * BaseClass for console commands.
+ * @package Piwik_Console
+ */
 class Command extends SymfonyCommand
 {
     public function __construct($name = null)
diff --git a/core/Controller.php b/core/Controller.php
index 6addbc5653..d3c17ae8a1 100644
--- a/core/Controller.php
+++ b/core/Controller.php
@@ -29,6 +29,7 @@ use Piwik\ViewDataTable;
  * It defines some helper functions controllers can use.
  *
  * @package Piwik
+ * @api
  */
 abstract class Controller
 {
diff --git a/core/Cookie.php b/core/Cookie.php
index d845049d22..4492fffb72 100644
--- a/core/Cookie.php
+++ b/core/Cookie.php
@@ -17,7 +17,6 @@ namespace Piwik;
  * - create a new cookie, set values, expiration date, etc. and save it
  *
  * @package Piwik
- * @api
  */
 class Cookie
 {
diff --git a/core/DataTable.php b/core/DataTable.php
index 078263e646..d6c71b9459 100644
--- a/core/DataTable.php
+++ b/core/DataTable.php
@@ -144,6 +144,8 @@ require_once PIWIK_INCLUDE_PATH . '/core/Common.php';
  *
  * @package Piwik
  * @subpackage DataTable
+ *
+ * @api
  */
 class DataTable
 {
diff --git a/core/Date.php b/core/Date.php
index 22580bd492..a32d7091a8 100644
--- a/core/Date.php
+++ b/core/Date.php
@@ -16,6 +16,7 @@ use Exception;
  * Date object widely used in Piwik.
  *
  * @package Piwik
+ * @api
  */
 class Date
 {
diff --git a/core/Db.php b/core/Db.php
index 25aed400d2..cb9224c76c 100644
--- a/core/Db.php
+++ b/core/Db.php
@@ -19,6 +19,7 @@ use Piwik\Config;
  * SQL wrapper
  *
  * @package PluginsFunctions
+ * @api
  */
 class Db
 {
@@ -510,4 +511,4 @@ class Db
             Log::debug(new Exception("Encountered deadlock: " . print_r($deadlockInfo, true)));
         }
     }
-}
\ No newline at end of file
+}
diff --git a/core/Filesystem.php b/core/Filesystem.php
index 5c7ea6d868..8dc797d00a 100644
--- a/core/Filesystem.php
+++ b/core/Filesystem.php
@@ -13,6 +13,11 @@ namespace Piwik;
 use Exception;
 use Piwik\Tracker\Cache;
 
+/**
+ * Class Filesystem
+ * @package Piwik
+ * @api
+ */
 class Filesystem
 {
     /**
diff --git a/core/Metrics.php b/core/Metrics.php
index 2a4f53dc2f..99704bcfb3 100644
--- a/core/Metrics.php
+++ b/core/Metrics.php
@@ -12,6 +12,8 @@ namespace Piwik;
 
 /**
  * This class holds the various mappings we use to internally store and manipulate metrics.
+ *
+ * @api
  */
 class Metrics
 {
diff --git a/core/MetricsFormatter.php b/core/MetricsFormatter.php
index 63794f3c81..4760c03f6f 100644
--- a/core/MetricsFormatter.php
+++ b/core/MetricsFormatter.php
@@ -12,6 +12,12 @@ namespace Piwik;
 
 use Piwik\Tracker\GoalManager;
 
+/**
+ * Class MetricsFormatter
+ * @package Piwik
+ *
+ * @api
+ */
 class MetricsFormatter
 {
     /**
diff --git a/core/Nonce.php b/core/Nonce.php
index 136db339af..ddd586ce24 100644
--- a/core/Nonce.php
+++ b/core/Nonce.php
@@ -24,6 +24,7 @@ use Piwik\Session\SessionNamespace;
  * - a mix of PRNGs (pseudo-random number generators) to increase entropy and make it less predictable
  *
  * @package Piwik
+ * @api
  */
 class Nonce
 {
diff --git a/core/Period/Day.php b/core/Period/Day.php
index a4ed18fbba..46e590c4ca 100644
--- a/core/Period/Day.php
+++ b/core/Period/Day.php
@@ -15,6 +15,7 @@ use Piwik\Period;
 /**
  * @package Piwik
  * @subpackage Period
+ * @api
  */
 class Day extends Period
 {
diff --git a/core/Period/Month.php b/core/Period/Month.php
index e53c5282d0..78ac50538e 100644
--- a/core/Period/Month.php
+++ b/core/Period/Month.php
@@ -16,6 +16,7 @@ use Piwik\Period\Day;
 /**
  * @package Piwik
  * @subpackage Period
+ * @api
  */
 class Month extends Period
 {
diff --git a/core/Period/Range.php b/core/Period/Range.php
index 4ee8baa2b5..06bd605311 100644
--- a/core/Period/Range.php
+++ b/core/Period/Range.php
@@ -22,6 +22,7 @@ use Piwik\Period\Week;
  *
  * @package Piwik
  * @subpackage Period
+ * @api
  */
 class Range extends Period
 {
diff --git a/core/Period/Week.php b/core/Period/Week.php
index 622bf4ba94..dd4b1d9c06 100644
--- a/core/Period/Week.php
+++ b/core/Period/Week.php
@@ -16,6 +16,7 @@ use Piwik\Period;
 /**
  * @package Piwik
  * @subpackage Period
+ * @api
  */
 class Week extends Period
 {
diff --git a/core/Period/Year.php b/core/Period/Year.php
index d56d693464..393c0b6878 100644
--- a/core/Period/Year.php
+++ b/core/Period/Year.php
@@ -17,6 +17,7 @@ use Piwik\Period\Month;
 /**
  * @package Piwik
  * @subpackage Period
+ * @api
  */
 class Year extends Period
 {
diff --git a/core/Piwik.php b/core/Piwik.php
index 4a4d2b67af..1b59f48e2c 100644
--- a/core/Piwik.php
+++ b/core/Piwik.php
@@ -65,6 +65,7 @@ class Piwik
      * ... and dies
      *
      * @param string $message
+     * @api
      */
     static public function exitWithErrorMessage($message)
     {
@@ -167,6 +168,7 @@ class Piwik
      * Get current user email address
      *
      * @return string
+     * @api
      */
     static public function getCurrentUserEmail()
     {
@@ -181,6 +183,7 @@ class Piwik
      * Returns Super User login
      *
      * @return string
+     * @api
      */
     static public function getSuperUserLogin()
     {
@@ -191,6 +194,7 @@ class Piwik
      * Returns Super User email
      *
      * @return string
+     * @api
      */
     static public function getSuperUserEmail()
     {
@@ -202,6 +206,7 @@ class Piwik
      * Get current user login
      *
      * @return string  login ID
+     * @api
      */
     static public function getCurrentUserLogin()
     {
@@ -212,6 +217,7 @@ class Piwik
      * Get current user's token auth
      *
      * @return string  Token auth
+     * @api
      */
     static public function getCurrentUserTokenAuth()
     {
@@ -224,6 +230,8 @@ class Piwik
      *
      * @param string $theUser
      * @return bool
+     *
+     * @api
      */
     static public function isUserIsSuperUserOrTheUser($theUser)
     {
@@ -240,6 +248,7 @@ class Piwik
      *
      * @param string $theUser
      * @throws NoAccessException  if the user is neither the super user nor the user $theUser
+     * @api
      */
     static public function checkUserIsSuperUserOrTheUser($theUser)
     {
@@ -257,6 +266,7 @@ class Piwik
      * Returns true if the current user is the Super User
      *
      * @return bool
+     * @api
      */
     static public function isUserIsSuperUser()
     {
@@ -272,6 +282,7 @@ class Piwik
      * Is user the anonymous user?
      *
      * @return bool  True if anonymouse; false otherwise
+     * @api
      */
     static public function isUserIsAnonymous()
     {
@@ -282,6 +293,7 @@ class Piwik
      * Checks if user is not the anonymous user.
      *
      * @throws NoAccessException  if user is anonymous.
+     * @api
      */
     static public function checkUserIsNotAnonymous()
     {
@@ -295,6 +307,7 @@ class Piwik
      * This should be used with great care as this gives the user all permissions.
      *
      * @param bool $bool  true to set current user as super user
+     * @api
      */
     static public function setUserIsSuperUser($bool = true)
     {
@@ -305,6 +318,7 @@ class Piwik
      * Check that user is the superuser
      *
      * @throws Exception if not the superuser
+     * @api
      */
     static public function checkUserIsSuperUser()
     {
@@ -315,7 +329,10 @@ class Piwik
      * Returns true if the user has admin access to the sites
      *
      * @param mixed $idSites
+     *
      * @return bool
+     *
+     * @api
      */
     static public function isUserHasAdminAccess($idSites)
     {
@@ -332,6 +349,7 @@ class Piwik
      *
      * @param mixed $idSites
      * @throws Exception if user doesn't have admin access to the sites
+     * @api
      */
     static public function checkUserHasAdminAccess($idSites)
     {
@@ -342,6 +360,7 @@ class Piwik
      * Returns true if the user has admin access to any sites
      *
      * @return bool
+     * @api
      */
     static public function isUserHasSomeAdminAccess()
     {
@@ -357,6 +376,7 @@ class Piwik
      * Check user has admin access to any sites
      *
      * @throws Exception if user doesn't have admin access to any sites
+     * @api
      */
     static public function checkUserHasSomeAdminAccess()
     {
@@ -368,6 +388,8 @@ class Piwik
      *
      * @param mixed $idSites
      * @return bool
+     *
+     * @api
      */
     static public function isUserHasViewAccess($idSites)
     {
@@ -384,6 +406,8 @@ class Piwik
      *
      * @param mixed $idSites
      * @throws Exception if user doesn't have view access to sites
+     *
+     * @api
      */
     static public function checkUserHasViewAccess($idSites)
     {
@@ -394,6 +418,8 @@ class Piwik
      * Returns true if the user has view access to any sites
      *
      * @return bool
+     *
+     * @api
      */
     static public function isUserHasSomeViewAccess()
     {
@@ -409,6 +435,8 @@ class Piwik
      * Check user has view access to any sites
      *
      * @throws Exception if user doesn't have view access to any sites
+     *
+     * @api
      */
     static public function checkUserHasSomeViewAccess()
     {
@@ -445,6 +473,8 @@ class Piwik
      * Returns the current module read from the URL (eg. 'API', 'UserSettings', etc.)
      *
      * @return string
+     *
+     * @api
      */
     static public function getModule()
     {
@@ -455,6 +485,8 @@ class Piwik
      * Returns the current action read from the URL
      *
      * @return string
+     *
+     * @api
      */
     static public function getAction()
     {
@@ -490,6 +522,8 @@ class Piwik
      * @param string $newAction   Target action
      * @param array $parameters  Parameters to modify in the URL
      * @return bool  false if the URL to redirect to is already this URL
+     *
+     * @api
      */
     static public function redirectToModule($newModule, $newAction = '', $parameters = array())
     {
@@ -509,6 +543,8 @@ class Piwik
      *
      * @param string $email
      * @return bool
+     *
+     * @api
      */
     static public function isValidEmailString($email)
     {
diff --git a/core/ScheduledTask.php b/core/ScheduledTask.php
index 4463daf89c..0f7dc3013b 100644
--- a/core/ScheduledTask.php
+++ b/core/ScheduledTask.php
@@ -19,6 +19,8 @@ use Piwik\ScheduledTime;
  *
  * @package Piwik
  * @subpackage ScheduledTask
+ *
+ * @api
  */
 class ScheduledTask
 {
diff --git a/core/SettingsPiwik.php b/core/SettingsPiwik.php
index e00ddf4330..5b82796df1 100644
--- a/core/SettingsPiwik.php
+++ b/core/SettingsPiwik.php
@@ -12,6 +12,12 @@ namespace Piwik;
 
 use Exception;
 
+/**
+ * Class SettingsPiwik
+ * @package Piwik
+ *
+ * @api
+ */
 class SettingsPiwik
 {
     /**
diff --git a/core/Site.php b/core/Site.php
index eb13215e34..495975c1f6 100644
--- a/core/Site.php
+++ b/core/Site.php
@@ -17,6 +17,7 @@ use Piwik\Plugins\SitesManager\API;
 /**
  *
  * @package Piwik
+ * @api
  */
 class Site
 {
diff --git a/core/Url.php b/core/Url.php
index ea8e07766e..3a03492f22 100644
--- a/core/Url.php
+++ b/core/Url.php
@@ -17,6 +17,7 @@ use Exception;
  * and handle URL redirection.
  *
  * @package Piwik
+ * @api
  */
 class Url
 {
diff --git a/core/UrlHelper.php b/core/UrlHelper.php
index a5a6db76ad..b411c6c6d1 100644
--- a/core/UrlHelper.php
+++ b/core/UrlHelper.php
@@ -10,6 +10,12 @@
  */
 namespace Piwik;
 
+/**
+ * Class UrlHelper
+ * @package Piwik
+ *
+ * @api
+ */
 class UrlHelper
 {
     /**
diff --git a/core/Version.php b/core/Version.php
index d4da3429ab..73b0025f92 100644
--- a/core/Version.php
+++ b/core/Version.php
@@ -15,6 +15,8 @@ namespace Piwik;
  * Piwik version information.
  *
  * @package Piwik
+ *
+ * @api
  */
 final class Version
 {
diff --git a/core/View.php b/core/View.php
index 8256f96ad5..f07ae88cb0 100644
--- a/core/View.php
+++ b/core/View.php
@@ -28,6 +28,8 @@ if (!defined('PIWIK_USER_PATH')) {
  * View class to render the user interface
  *
  * @package Piwik
+ *
+ * @api
  */
 class View implements ViewInterface
 {
diff --git a/core/ViewDataTable.php b/core/ViewDataTable.php
index 4c3ef0c0ff..d345922cdf 100644
--- a/core/ViewDataTable.php
+++ b/core/ViewDataTable.php
@@ -107,6 +107,8 @@ use Piwik\ViewDataTable\Visualization;
  * @see factory() for all the available output (cloud tags, html table, pie chart, vertical bar chart)
  * @package Piwik
  * @subpackage ViewDataTable
+ *
+ * @api
  */
 class ViewDataTable
 {
diff --git a/core/functions.php b/core/functions.php
index 098b4e96d8..b1cf05abc7 100644
--- a/core/functions.php
+++ b/core/functions.php
@@ -89,6 +89,7 @@ namespace {
      * @param string $message Translation string index
      * @param array $args sprintf arguments
      * @return string
+     * @api
      */
     function Piwik_TranslateException($message, $args = array())
     {
@@ -142,6 +143,7 @@ namespace {
      * @param string $url
      * @param boolean $displayedForCurrentUser
      * @param int $order
+     * @api
      */
     function Piwik_AddAdminMenu($adminMenuName, $url, $displayedForCurrentUser = true, $order = 10)
     {
@@ -156,6 +158,7 @@ namespace {
      * @param string $url
      * @param boolean $displayedForCurrentUser
      * @param int $order
+     * @api
      */
     function Piwik_AddAdminSubMenu($adminMenuName, $adminSubMenuName, $url, $displayedForCurrentUser = true, $order = 10)
     {
@@ -192,6 +195,7 @@ namespace {
      * @param string $url
      * @param boolean $displayedForCurrentUser
      * @param int $order
+     * @api
      */
     function Piwik_AddMenu($mainMenuName, $subMenuName, $url, $displayedForCurrentUser = true, $order = 10)
     {
@@ -243,6 +247,7 @@ namespace {
      * @param int         $order
      * @param bool        $isHTML
      * @param bool|string $tooltip Tooltip to display.
+     * @api
      */
     function Piwik_AddTopMenu($topMenuName, $data, $displayedForCurrentUser = true, $order = 10, $isHTML = false,
                               $tooltip = false)