refs #2256

git-svn-id: http://dev.piwik.org/svn/trunk@4297 59fd770c-687e-43c8-a1e3-f5a4ff64c105

8 files changed, 118 insertions, 81 deletions

diff --git a/core/Db/Schema.php b/core/Db/Schema.php
index 48278e94a8..4a5d3bb4f4 100644
--- a/core/Db/Schema.php
+++ b/core/Db/Schema.php
@@ -258,7 +258,10 @@ class Piwik_Db_Schema
 }
 
 /**
+ * Database schema interface
+ *
  * @package Piwik
+ * @subpackage Piwik_Db
  */
 interface Piwik_Db_Schema_Interface
 {
diff --git a/core/PluginsManager.php b/core/PluginsManager.php
index 1a5af639ca..44d8b43372 100644
--- a/core/PluginsManager.php
+++ b/core/PluginsManager.php
@@ -1,11 +1,11 @@
 <?php
 /**
  * Piwik - Open source web analytics
- * 
+ *
  * @link http://piwik.org
  * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
  * @version $Id$
- * 
+ *
  * @category Piwik
  * @package Piwik
  */
@@ -26,6 +26,8 @@ require_once PIWIK_INCLUDE_PATH . '/core/PluginsFunctions/WidgetsList.php';
 require_once PIWIK_INCLUDE_PATH . '/core/PluginsFunctions/Sql.php';
 
 /**
+ * Plugin manager
+ *
  * @package Piwik
  * @subpackage Piwik_PluginsManager
  */
@@ -35,27 +37,27 @@ class Piwik_PluginsManager
 	 * @var Event_Dispatcher
 	 */
 	public $dispatcher;
-	
+
 	protected $pluginsToLoad = array();
 
 	protected $doLoadPlugins = true;
 	protected $loadedPlugins = array();
-	
+
 	protected $doLoadAlwaysActivatedPlugins = true;
 	protected $pluginToAlwaysActivate = array(
-		'CoreHome', 
-		'CoreUpdater', 
-		'CoreAdminHome', 
-		'CorePluginsAdmin', 
-		'Installation', 
-		'SitesManager', 
+		'CoreHome',
+		'CoreUpdater',
+		'CoreAdminHome',
+		'CorePluginsAdmin',
+		'Installation',
+		'SitesManager',
 		'UsersManager',
 		'API',
 		'Proxy',
 	);
 
 	static private $instance = null;
-	
+
 	/**
 	 * Returns the singleton Piwik_PluginsManager
 	 *
@@ -69,28 +71,34 @@ class Piwik_PluginsManager
 		}
 		return self::$instance;
 	}
-	
+
 	private function __construct()
 	{
 		$this->dispatcher = Event_Dispatcher::getInstance();
 	}
-	
+
+	/**
+	 * Returns true if plugin is always activated
+	 *
+	 * @param string $name Name of plugin
+	 * @return bool
+	 */
 	public function isPluginAlwaysActivated( $name )
 	{
 		return in_array( $name, $this->pluginToAlwaysActivate);
 	}
-	
+
 	public function isPluginActivated( $name )
 	{
 		return in_array( $name, $this->pluginsToLoad)
-			|| $this->isPluginAlwaysActivated( $name );		
+			|| $this->isPluginAlwaysActivated( $name );
 	}
-	
+
 	public function isPluginLoaded( $name )
 	{
 		return isset($this->loadedPlugins[$name]);
 	}
-	
+
 	/**
 	 * Reads the directories inside the plugins/ directory and returns their names in an array
 	 *
@@ -112,7 +120,7 @@ class Piwik_PluginsManager
 			unset($plugins[$key]);
 			Zend_Registry::get('config')->Plugins = $plugins;
 		}
-		
+
 		$pluginsTracker = Zend_Registry::get('config')->Plugins_Tracker->Plugins_Tracker;
 		if(!is_null($pluginsTracker))
 		{
@@ -124,12 +132,12 @@ class Piwik_PluginsManager
 				Zend_Registry::get('config')->Plugins_Tracker = array('Plugins_Tracker' => $pluginsTracker);
 			}
 		}
-		
+
 		// Delete merged js/css files to force regenerations to exclude the deactivated plugin
 		Piwik_AssetManager::removeMergedAssets();
 		Piwik_View::clearCompiledTemplates();
 	}
-	
+
 	public function installLoadedPlugins()
 	{
 		foreach($this->getLoadedPlugins() as $plugin)
@@ -138,10 +146,10 @@ class Piwik_PluginsManager
 				$this->installPluginIfNecessary( $plugin );
 			}catch(Exception $e){
 				echo $e->getMessage();
-			}				
+			}
 		}
 	}
-	
+
 	public function activatePlugin($pluginName)
 	{
 		$plugins = Zend_Registry::get('config')->Plugins->Plugins->toArray();
@@ -149,28 +157,28 @@ class Piwik_PluginsManager
 		{
 			throw new Exception("Plugin '$pluginName' already activated.");
 		}
-		
+
 		$existingPlugins = $this->readPluginsDirectory();
 		if( array_search($pluginName,$existingPlugins) === false)
 		{
 			throw new Exception("Unable to find the plugin '$pluginName'.");
 		}
-		
+
 		$plugin = $this->loadPlugin($pluginName);
-		
+
 		$this->installPluginIfNecessary($plugin);
-		
+
 		// we add the plugin to the list of activated plugins
 		$plugins[] = $pluginName;
-		
+
 		// the config file will automatically be saved with the new plugin
 		Zend_Registry::get('config')->Plugins = $plugins;
-		
+
 		// Delete merged js/css files to force regenerations to include the activated plugin
 		Piwik_AssetManager::removeMergedAssets();
-		Piwik_View::clearCompiledTemplates();		
+		Piwik_View::clearCompiledTemplates();
 	}
-	
+
 	public function loadPlugins( array $pluginsToLoad )
 	{
 		// case no plugins to load
@@ -181,7 +189,7 @@ class Piwik_PluginsManager
 		$this->pluginsToLoad = $pluginsToLoad;
 		$this->reloadPlugins();
 	}
-	
+
 	public function doNotLoadPlugins()
 	{
 		$this->doLoadPlugins = false;
@@ -214,7 +222,7 @@ class Piwik_PluginsManager
 			$plugin->postLoad();
 		}
 	}
-	
+
 	/**
 	 * Returns an array containing the plugins class names (eg. 'Piwik_UserCountry' and NOT 'UserCountry')
 	 *
@@ -224,14 +232,14 @@ class Piwik_PluginsManager
 	{
 		return array_map('get_class', $this->getLoadedPlugins());
 	}
-	
+
 	/**
 	 * Returns an array of key,value with the following format: array(
 	 * 		'UserCountry' => Piwik_Plugin $pluginObject,
 	 * 		'UserSettings' => Piwik_Plugin $pluginObject,
 	 * 	);
 	 *
-	 * @return array 
+	 * @return array
 	 */
 	public function getLoadedPlugins()
 	{
@@ -239,7 +247,7 @@ class Piwik_PluginsManager
 	}
 
 	/**
-	 * Returns the given Piwik_Plugin object 
+	 * Returns the given Piwik_Plugin object
 	 *
 	 * @param string $name
 	 * @return Piwik_Piwik
@@ -252,11 +260,11 @@ class Piwik_PluginsManager
 		}
 		return $this->loadedPlugins[$name];
 	}
-	
+
 	/**
 	 * Load the plugins classes installed.
 	 * Register the observers for every plugin.
-	 * 
+	 *
 	 */
 	private function reloadPlugins()
 	{
@@ -266,12 +274,12 @@ class Piwik_PluginsManager
 		{
 			$this->pluginsToLoad = array_merge($this->pluginsToLoad, $this->pluginToAlwaysActivate);
 		}
-		
+
 		foreach($this->pluginsToLoad as $pluginName)
 		{
 			if(!$this->isPluginLoaded($pluginName))
 			{
-				$newPlugin = $this->loadPlugin($pluginName);	
+				$newPlugin = $this->loadPlugin($pluginName);
 				if($this->doLoadPlugins
 					&& $this->isPluginActivated($pluginName))
 				{
@@ -280,10 +288,10 @@ class Piwik_PluginsManager
 			}
 		}
 	}
-	
+
 	/**
 	 * Loads the plugin filename and instantiates the plugin with the given name, eg. UserCountry
-	 * Do NOT give the class name ie. Piwik_UserCountry, but give the plugin name ie. UserCountry 
+	 * Do NOT give the class name ie. Piwik_UserCountry, but give the plugin name ie. UserCountry
 	 *
 	 * @param string $pluginName
 	 * @return Piwik_Plugin
@@ -296,12 +304,12 @@ class Piwik_PluginsManager
 		}
 		$pluginFileName = $pluginName . '/' . $pluginName . '.php';
 		$pluginClassName = 'Piwik_'.$pluginName;
-		
+
 		if( !Piwik_Common::isValidFilename($pluginName))
 		{
 			throw new Exception("The plugin filename '$pluginFileName' is not a valid filename");
 		}
-		
+
 		$path = PIWIK_INCLUDE_PATH . '/plugins/' . $pluginFileName;
 
 		if(!file_exists($path))
@@ -313,13 +321,13 @@ class Piwik_PluginsManager
 		// Don't remove this.
 		// Our autoloader can't find plugins/PluginName/PluginName.php
 		require_once $path; // prefixed by PIWIK_INCLUDE_PATH
-		
+
 		if(!class_exists($pluginClassName, false))
 		{
 			throw new Exception("The class $pluginClassName couldn't be found in the file '$path'");
 		}
 		$newPlugin = new $pluginClassName();
-		
+
 		if(!($newPlugin instanceof Piwik_Plugin))
 		{
 			throw new Exception("The plugin $pluginClassName in the file $path must inherit from Piwik_Plugin.");
@@ -329,8 +337,10 @@ class Piwik_PluginsManager
 
 		return $newPlugin;
 	}
-	
+
 	/**
+	 * Unload plugin
+	 *
 	 * @param Piwik_Plugin $plugin
 	 */
 	public function unloadPlugin( $plugin )
@@ -340,7 +350,7 @@ class Piwik_PluginsManager
 			$plugin = $this->loadPlugin( $plugin );
 		}
 		$hooks = $plugin->getListHooksRegistered();
-			
+
 		foreach($hooks as $hookName => $methodToCall)
 		{
 			$success = $this->dispatcher->removeObserver( array( $plugin, $methodToCall), $hookName );
@@ -351,7 +361,7 @@ class Piwik_PluginsManager
 		}
 		unset($this->loadedPlugins[$plugin->getPluginName()]);
 	}
-	
+
 	public function unloadPlugins()
 	{
 		$pluginsLoaded = $this->getLoadedPlugins();
@@ -364,45 +374,49 @@ class Piwik_PluginsManager
 	private function installPlugins()
 	{
 		foreach($this->getLoadedPlugins() as $plugin)
-		{		
+		{
 			$this->installPlugin($plugin);
 		}
 	}
-	
+
 	private function installPlugin( Piwik_Plugin $plugin )
 	{
 		try{
 			$plugin->install();
 		} catch(Exception $e) {
-			throw new Piwik_PluginsManager_PluginException($plugin->getPluginName(), $e->getMessage());		}	
+			throw new Piwik_PluginsManager_PluginException($plugin->getPluginName(), $e->getMessage());		}
 	}
-	
-	
+
+
 	/**
 	 * For the given plugin, add all the observers of this plugin.
+	 *
+	 * @param Piwik_Plugin $plugin
 	 */
 	private function addPluginObservers( Piwik_Plugin $plugin )
 	{
 		$hooks = $plugin->getListHooksRegistered();
-		
+
 		foreach($hooks as $hookName => $methodToCall)
 		{
 			$this->dispatcher->addObserver( array( $plugin, $methodToCall), $hookName );
 		}
 	}
-	
+
 	/**
 	 * Add a plugin in the loaded plugins array
 	 *
-	 * @param string plugin name without prefix (eg. 'UserCountry')
+	 * @param string $pluginName plugin name without prefix (eg. 'UserCountry')
 	 * @param Piwik_Plugin $newPlugin
 	 */
 	private function addLoadedPlugin( $pluginName, Piwik_Plugin $newPlugin )
 	{
 		$this->loadedPlugins[$pluginName] = $newPlugin;
 	}
-	
+
 	/**
+	 * Load translation
+	 *
 	 * @param Piwik_Plugin $plugin
 	 * @param string $langCode
 	 */
@@ -414,27 +428,27 @@ class Piwik_PluginsManager
 			return ;
 		}
 
-		$infos = $plugin->getInformation();		
+		$infos = $plugin->getInformation();
 		if(!isset($infos['translationAvailable']))
 		{
 			$infos['translationAvailable'] = false;
 		}
 		$translationAvailable = $infos['translationAvailable'];
-		
+
 		if(!$translationAvailable)
 		{
 			return;
 		}
-	
+
 		$pluginName = $plugin->getPluginName();
-		
+
 		$path = PIWIK_INCLUDE_PATH . '/plugins/' . $pluginName .'/lang/%s.php';
-		
+
 		$defaultLangPath = sprintf($path, $langCode);
 		$defaultEnglishLangPath = sprintf($path, 'en');
-		
+
 		$translations = array();
-				
+
 		if(file_exists($defaultLangPath))
 		{
 			require $defaultLangPath;
@@ -449,7 +463,7 @@ class Piwik_PluginsManager
 		}
 		Piwik_Translate::getInstance()->mergeTranslationArray($translations);
 	}
-	
+
 	/**
 	 * @return array
 	 */
@@ -462,22 +476,22 @@ class Piwik_PluginsManager
 		$pluginNames = Zend_Registry::get('config')->PluginsInstalled->PluginsInstalled->toArray();
 		return $pluginNames;
 	}
-	
+
 	private function installPluginIfNecessary( Piwik_Plugin $plugin )
 	{
 		$pluginName = $plugin->getPluginName();
-		
+
 		// is the plugin already installed or is it the first time we activate it?
 		$pluginsInstalled = $this->getInstalledPluginsName();
 		if(!in_array($pluginName,$pluginsInstalled))
 		{
 			$this->installPlugin($plugin);
 			$pluginsInstalled[] = $pluginName;
-			Zend_Registry::get('config')->PluginsInstalled = array('PluginsInstalled' => $pluginsInstalled);	
+			Zend_Registry::get('config')->PluginsInstalled = array('PluginsInstalled' => $pluginsInstalled);
 		}
-		
+
 		$information = $plugin->getInformation();
-		
+
 		// if the plugin is to be loaded during the statistics logging
 		if(isset($information['TrackerPlugin'])
 			&& $information['TrackerPlugin'] === true)
@@ -504,13 +518,13 @@ class Piwik_PluginsManager
  * @package Piwik
  * @subpackage Piwik_PluginsManager
  */
-class Piwik_PluginsManager_PluginException extends Exception 
+class Piwik_PluginsManager_PluginException extends Exception
 {
 	function __construct($pluginName, $message)
 	{
 		parent::__construct("There was a problem installing the plugin ". $pluginName . ": " . $message. "
-				If this plugin has already been installed, and if you want to hide this message</b>, you must add the following line under the 
-				[PluginsInstalled] 
+				If this plugin has already been installed, and if you want to hide this message</b>, you must add the following line under the
+				[PluginsInstalled]
 				entry in your config/config.ini.php file:
 				PluginsInstalled[] = $pluginName" );
 	}
@@ -518,12 +532,12 @@ class Piwik_PluginsManager_PluginException extends Exception
 
 /**
  * Post an event to the dispatcher which will notice the observers
- * 
- * @param $eventName The event name
- * @param $object Object, array or string that the listeners can read and/or modify.
+ *
+ * @param string $eventName The event name
+ * @param mixed $object Object, array or string that the listeners can read and/or modify.
  *                Listeners can call $object =& $notification->getNotificationObject(); to fetch and then modify this variable.
- * @param $info Additional array of data that can be used by the listeners, but not edited
- * @param $pending Should the notification be posted to plugins that register after the notification was sent?
+ * @param array $info Additional array of data that can be used by the listeners, but not edited
+ * @param bool $pending Should the notification be posted to plugins that register after the notification was sent?
  * @return void
  */
 function Piwik_PostEvent( $eventName,  &$object = null, $info = array(), $pending = false )
@@ -534,6 +548,9 @@ function Piwik_PostEvent( $eventName,  &$object = null, $info = array(), $pendin
 
 /**
  * Register an action to execute for a given event
+ *
+ * @param string $hookName Name of event
+ * @param function $function Callback hook
  */
 function Piwik_AddAction( $hookName, $function )
 {
@@ -541,13 +558,23 @@ function Piwik_AddAction( $hookName, $function )
 }
 
 /**
+ * Event notification
+ *
  * @package Piwik
+ *
  * @see Event_Notification, libs/Event/Notification.php
  * @link http://pear.php.net/package/Event_Dispatcher/docs/latest/Event_Dispatcher/Event_Notification.html
  */
 class Piwik_Event_Notification extends Event_Notification
 {
 	static $showProfiler = false;
+
+	/**
+	 * Use notification counter to profile runtime execution
+	 * time and memory usage.
+	 *
+	 * @param  mixed $callback Callback function
+	 */
 	function increaseNotificationCount(/* array($className|object, $method) */) {
 		parent::increaseNotificationCount();
 		if(self::$showProfiler && func_num_args() == 1)
diff --git a/core/Session.php b/core/Session.php
index e92aaf328e..2246be9f8b 100644
--- a/core/Session.php
+++ b/core/Session.php
@@ -14,6 +14,7 @@
  * Session initialization.
  * 
  * @package Piwik
+ * @subpackage Piwik_Session
  */
 class Piwik_Session extends Zend_Session
 {
diff --git a/core/Session/Namespace.php b/core/Session/Namespace.php
index 919928298d..2393508048 100644
--- a/core/Session/Namespace.php
+++ b/core/Session/Namespace.php
@@ -14,6 +14,7 @@
  * Session namespace.
  * 
  * @package Piwik
+ * @subpackage Piwik_Session
  */
 class Piwik_Session_Namespace extends Zend_Session_Namespace
 {
diff --git a/core/iUnzip.php b/core/Unzip/Interface.php
index 0d06f8ea9f..cd86202281 100644
--- a/core/iUnzip.php
+++ b/core/Unzip/Interface.php
@@ -14,8 +14,9 @@
  * Unzip interface
  *
  * @package Piwik
+ * @subpackage Piwik_Unzip
  */
-interface Piwik_iUnzip
+interface Piwik_Unzip_Interface
 {
 	/**
 	 * Constructor
diff --git a/core/Unzip/PclZip.php b/core/Unzip/PclZip.php
index 002b84b647..b47b766dc6 100644
--- a/core/Unzip/PclZip.php
+++ b/core/Unzip/PclZip.php
@@ -19,8 +19,9 @@ require_once PIWIK_INCLUDE_PATH . '/libs/PclZip/pclzip.lib.php';
  * Unzip wrapper around PclZip
  *
  * @package Piwik
+ * @subpackage Piwik_Unzip
  */
-class Piwik_Unzip_PclZip implements Piwik_iUnzip
+class Piwik_Unzip_PclZip implements Piwik_Unzip_Interface
 {
 	private $pclzip;
 	public $filename;
diff --git a/core/Unzip/ZipArchive.php b/core/Unzip/ZipArchive.php
index 1e0c93ffda..0a84463482 100644
--- a/core/Unzip/ZipArchive.php
+++ b/core/Unzip/ZipArchive.php
@@ -14,8 +14,9 @@
  * Unzip wrapper around ZipArchive
  *
  * @package Piwik
+ * @subpackage Piwik_Unzip
  */
-class Piwik_Unzip_ZipArchive  implements Piwik_iUnzip
+class Piwik_Unzip_ZipArchive  implements Piwik_Unzip_Interface
 {
 	private $ziparchive;
 	public $filename;
diff --git a/core/iView.php b/core/iView.php
index d801fad842..4b985f69f7 100644
--- a/core/iView.php
+++ b/core/iView.php
@@ -11,6 +11,8 @@
  */
 
 /**
+ * Rendering interface for Piwik_View and Piwik_Visualization
+ *
  * @package Piwik
  */
 interface Piwik_iView