code documentation

mvc specification
finished referer API implementation

62 files changed, 712 insertions, 210 deletions

diff --git a/modules/API/APIable.php b/modules/API/APIable.php
index f3ce32a1fe..9a9feea6f7 100755
--- a/modules/API/APIable.php
+++ b/modules/API/APIable.php
@@ -1,4 +1,10 @@
 <?php
+/**
+ * This class is the parent class of all the modules that can be called using the 
+ * API Proxy.
+ * 
+ * @package Piwik_API
+ */
 class Piwik_Apiable 
 {
 	static public $methodsNotToPublish = array();
@@ -7,6 +13,13 @@ class Piwik_Apiable
 	{
 	}
 
+	/**
+	 * Register a public method as "not to be published in the API".
+	 * Sometimes methods have to be marked as public to be used by other classes but
+	 * we don't want these methods to be called from outside the application.
+	 * 
+	 * @param string Method name not to be published
+	 */
 	protected function doNotPublishMethod( $methodName )
 	{
 		if(!method_exists($this, $methodName))
@@ -16,4 +29,3 @@ class Piwik_Apiable
 		$this->methodsNotToPublish[] = $methodName;
 	}
 }
-?>
\ No newline at end of file
diff --git a/modules/API/Proxy.php b/modules/API/Proxy.php
index f051024eee..35d2b6e0e8 100755
--- a/modules/API/Proxy.php
+++ b/modules/API/Proxy.php
@@ -1,4 +1,15 @@
 <?php
+/**
+ * 
+ * The API Proxy receives all the API calls requests and forwards them to the given module.
+ *  
+ * It registers all the APIable modules (@see Piwik_Apiable)
+ * The class checks that a call to the API has to correct number of parameters.
+ * The proxy has the knowledge of every method available, and their parameters and default value.
+ * It also logs the calls performances (time spent, parameter values, etc.)
+ * 
+ * @package Piwik_API
+ */
 class Piwik_API_Proxy
 {
 	static $classCalled = null;
@@ -21,6 +32,17 @@ class Piwik_API_Proxy
 		return self::$instance;
 	}
 	
+	/**
+	 * Registers the API information of a given module.
+	 * 
+	 * The module to register must be
+	 * - extending the Piwik_Apiable class
+	 * - a singleton (providing a getInstance() method)
+	 * - the API file must be located in plugins/MODULE/API.php
+	 *   for example plugins/Referers/API.php
+	 * 
+	 * The method will introspect the methods, their parameters, etc. 
+	 */
 	public function registerClass( $fileName )
 	{		
 		if(isset($this->alreadyRegistered[$fileName]))
@@ -96,7 +118,7 @@ class Piwik_API_Proxy
 					$aParameters[$nameVariable] = $defaultValue;
 				}
 				$this->api[$class][$name]['parameters'] = $aParameters;
-				$this->api[$class][$name]['numberOfRequiredParameters'] = $method->getNumberOfParameters();
+				$this->api[$class][$name]['numberOfRequiredParameters'] = $method->getNumberOfRequiredParameters();
 				
 				Piwik::log("- $name is public ".$this->getStrListParameters($class, $name));				
 			}
@@ -105,6 +127,12 @@ class Piwik_API_Proxy
 		$this->alreadyRegistered[$fileName] = true;
 	}
 	
+	/**
+	 * Returns the methods $class.$name parameters (and default value if provided)
+	 * as a string.
+	 * 
+	 * Example: [ idSite, period, date = today ]
+	 */
 	private function getStrListParameters($class, $name)
 	{
 		$aParameters = $this->getParametersList($class, $name);
@@ -112,7 +140,7 @@ class Piwik_API_Proxy
 		foreach($aParameters as $nameVariable=> $defaultValue)
 		{
 			$str = $nameVariable;
-			if(!empty($defaultValue))
+			if($defaultValue !== Piwik_API_Proxy::NO_DEFAULT_VALUE)
 			{
 				$str .= " = $defaultValue";
 			}
@@ -137,11 +165,17 @@ class Piwik_API_Proxy
 		return $this->api[$class][$name]['parameters'];
 	}
 	
+	/**
+	 * Returns the number of required parameters (parameters without default values).
+	 */
 	private function getNumberOfRequiredParameters($class, $name)
 	{
 		return $this->api[$class][$name]['numberOfRequiredParameters'];
 	}
 	
+	/**
+	 * Returns true if the method is found in the API
+	 */
 	private function isMethodAvailable( $className, $methodName)
 	{
 		return isset($this->api[$className][$methodName]);
@@ -153,6 +187,9 @@ class Piwik_API_Proxy
 		return $this;
 	}	
 	
+	/**
+	 * 
+	 */
 	private function checkNumberOfParametersMatch($className, $methodName, $parameters)
 	{
 		$nbParamsGiven = count($parameters);
@@ -170,6 +207,11 @@ class Piwik_API_Proxy
 		}
 	}
 	
+	/**
+	 * Checks that the class is a Singleton (presence of the getInstance() method)
+	 * 
+	 * @throws exception If the class is not a Singleton
+	 */
 	private function checkClassIsSingleton($className)
 	{
 		if(!method_exists($className, "getInstance"))
@@ -178,6 +220,11 @@ class Piwik_API_Proxy
 		}
 	}
 	
+	/**
+	 * Checks that the method exists in the class 
+	 * 
+	 * @throws exception If the method is not found
+	 */	
 	public function checkMethodExists($className, $methodName)
 	{
 		if(!$this->isMethodAvailable($className, $methodName))
@@ -185,12 +232,25 @@ class Piwik_API_Proxy
 			throw new Exception("The method '$methodName' does not exist or is not available in the module '".$className."'.");
 		}
 	}
-		
-	public function getClassNameFromModule($module)
+	
+	/**
+	 * Returns the API class name given the module name.
+	 * 
+	 * For exemple for $module = 'Referers' it returns 'Piwik_Referers_API' 
+	 * Piwik_Referers_API is the class that extends Piwik_Apiable 
+	 * and that contains the methods to be published in the API.
+	 */
+	protected  function getClassNameFromModule($module)
 	{
 		$class = Piwik::prefixClass($module ."_API");
 		return $class;
 	}
+	
+	/**
+	 * Method always called when making an API request.
+	 * It checks several things before actually calling the real method on the given module.
+	 * It also logs the API calls, with the parameters values, the returned value, the performance, etc.
+	 */
 	public function __call($methodName, $parameterValues )
 	{
 		$returnedValue = null;
@@ -228,6 +288,7 @@ class Piwik_API_Proxy
 		}
 		catch( Exception $e)
 		{
+			//TODO replace with nice error message
 			Piwik::log("<br>\n Error during API call {$className}.{$methodName}... 
 					<br>\n => ". $e->getMessage());
 
@@ -238,4 +299,3 @@ class Piwik_API_Proxy
 		return $returnedValue;
 	}
 }
-?>
\ No newline at end of file
diff --git a/modules/API/Request.php b/modules/API/Request.php
index 96211e1bc3..58204ac631 100644
--- a/modules/API/Request.php
+++ b/modules/API/Request.php
@@ -1,7 +1,31 @@
 <?php
-
+/**
+ * An API request is the object used to make a call to the API and get the result.
+ * The request has the form of a normal GET request, ie. parameter_1=X&parameter_2=Y
+ * 
+ * Example: 
+ * $request = new Piwik_API_Request('
+ * 				method=UserSettings.getWideScreen
+ * 				&idSite=1
+ *  			&date=yesterday
+ * 				&period=week
+ *				&format=xml
+ *				&filter_limit=5
+ *				&filter_offset=0
+ *	');
+ *	$result = $request->process();
+ *  echo $result;
+ * 
+ * @package Piwik_API
+ */
 class Piwik_API_Request
 {
+	/**
+	 * @param string GET request that defines the API call (must at least contain a "method" parameter) 
+	 *  Example: method=UserSettings.getWideScreen&idSite=1&date=yesterday&period=week&format=xml
+	 * 	If a request is not provided, then we use the $_REQUEST superglobal and fetch
+	 * 	the values directly from the HTTP GET query.
+	 */
 	function __construct($request = null)
 	{
 		$requestArray = $_REQUEST;
@@ -15,6 +39,11 @@ class Piwik_API_Request
 		$this->requestToUse = $requestArray;
 	}
 	
+	/**
+	 * Returns array( $class, $method) from the given string $class.$method
+	 * 
+	 * @return array
+	 */
 	private function extractModuleAndMethod($parameter)
 	{
 		$a = explode('.',$parameter);
@@ -25,68 +54,92 @@ class Piwik_API_Request
 		return $a;
 	}
 	
+	/**
+	 * Handles the request to the API.
+	 * It first checks that the method called (parameter 'method') is available in the module (it means that the method exists and is public)
+	 * It then reads the parameters from the request string and throws an exception if there are absent parameters.
+	 * It then calls the API Proxy which will call the method.
+	 * If the data resulted from the API call is a Piwik_DataTable then 
+	 * 		- we apply the standard filters if the parameters have been found
+	 * 		  in the URL. For example to offset,limit the Table you can add the following parameters to any API
+	 *  	  call that returns a DataTable: filter_limit=10&filter_offset=20
+	 * 		- we apply the filters that have been previously queued on the DataTable
+	 * 		- we apply the renderer that generate the DataTable in a given format (XML, PHP, HTML, JSON, etc.) 
+	 * 		  the format can be changed using the 'format' parameter in the request.
+	 *        Example: format=xml
+	 * 
+	 * @return mixed The data resulting from the API call  
+	 */
 	public function process()
 	{
-		// read parameters
-		$moduleMethod = Piwik_Common::getRequestVar('method', null, null, $this->requestToUse);
-		
-		list($module, $method) = $this->extractModuleAndMethod($moduleMethod); 
-		
-		if(!Piwik_PluginsManager::getInstance()->isPluginEnabled($module))
-		{
-			throw new Exception("The plugin '$module' is not enabled.");
-		}
-		// call the method via the PublicAPI class
-		$api = Piwik_Api_Proxy::getInstance();
-		$api->registerClass($module);
-		
-		// read method to call meta information
-		$className = "Piwik_" . $module . "_API";
-		
-		// check method exists
-		$api->checkMethodExists($className, $method);
-		
-		$parameters = $api->getParametersList($className, $method);
-		
-		$finalParameters = array();
-		foreach($parameters as $name => $defaultValue)
-		{
-			try{
-				// there is a default value specified
-				if($defaultValue !== Piwik_API_Proxy::NO_DEFAULT_VALUE)
-				{
-					$requestValue = Piwik_Common::getRequestVar($name, $defaultValue, null, $this->requestToUse);
-				}
-				else
-				{
-					$requestValue = Piwik_Common::getRequestVar($name, null, null, $this->requestToUse);				
-				}
-			} catch(Exception $e) {
-				Piwik::error("The required variable '$name' is not correct or has not been found in the API Request. <br>\n ".var_export($this->requestToUse, true));
-			}			
-			$finalParameters[] = $requestValue;
-		}
-		
-		$returnedValue = call_user_func_array( array( $api->$module, $method), $finalParameters );
-		
-		$toReturn = $returnedValue;
-		
-		// If the returned value is an object DataTable we
-		// apply the set of generic filters if asked in the URL
-		// and we render the DataTable according to the format specified in the URL
-		if($returnedValue instanceof Piwik_DataTable)
-		{
-			$dataTable = $returnedValue;
+		try {
+			
+			// read parameters
+			$moduleMethod = Piwik_Common::getRequestVar('method', null, null, $this->requestToUse);
 			
-			$this->applyDataTableGenericFilters($dataTable);
-			$dataTable->applyQueuedFilters();
-			$toReturn = $this->getRenderedDataTable($dataTable);
+			list($module, $method) = $this->extractModuleAndMethod($moduleMethod); 
 			
+			if(!Piwik_PluginsManager::getInstance()->isPluginEnabled($module))
+			{
+				throw new Exception("The plugin '$module' is not enabled.");
+			}
+			// call the method via the PublicAPI class
+			$api = Piwik_Api_Proxy::getInstance();
+			$api->registerClass($module);
+			
+			// read method to call meta information
+			$className = "Piwik_" . $module . "_API";
+			
+			// check method exists
+			$api->checkMethodExists($className, $method);
+			
+			$parameters = $api->getParametersList($className, $method);
+			
+			$finalParameters = array();
+			foreach($parameters as $name => $defaultValue)
+			{
+				try{
+					// there is a default value specified
+					if($defaultValue !== Piwik_API_Proxy::NO_DEFAULT_VALUE)
+					{
+						$requestValue = Piwik_Common::getRequestVar($name, $defaultValue, null, $this->requestToUse);
+					}
+					else
+					{
+						$requestValue = Piwik_Common::getRequestVar($name, null, null, $this->requestToUse);				
+					}
+				} catch(Exception $e) {
+					Piwik::error("The required variable '$name' is not correct or has not been found in the API Request. <br>\n ".var_export($this->requestToUse, true));
+				}			
+				$finalParameters[] = $requestValue;
+			}
+			
+			$returnedValue = call_user_func_array( array( $api->$module, $method), $finalParameters );
+			
+			$toReturn = $returnedValue;
+			
+			// If the returned value is an object DataTable we
+			// apply the set of generic filters if asked in the URL
+			// and we render the DataTable according to the format specified in the URL
+			if($returnedValue instanceof Piwik_DataTable)
+			{
+				$dataTable = $returnedValue;
+				
+				$this->applyDataTableGenericFilters($dataTable);
+				$dataTable->applyQueuedFilters();
+				$toReturn = $this->getRenderedDataTable($dataTable);
+				
+			}
+		} catch(Exception $e ) {
+			$toReturn = 'XML ERROR TEMPLATE TODO';
 		}
-		
 		return $toReturn;
 	}
 	
+	/**
+	 * Apply the specified renderer to the DataTable
+	 * @return Piwik_DataTable
+	 */
 	protected function getRenderedDataTable($dataTable)
 	{
 		// Renderer
@@ -98,6 +151,10 @@ class Piwik_API_Request
 		return $toReturn;
 	}
 	
+	/**
+	 * Applys generic filters to the DataTable object resulting from the API Call.
+	 * @return void
+	 */
 	protected function applyDataTableGenericFilters($dataTable)
 	{
 		
@@ -111,20 +168,20 @@ class Piwik_API_Request
 		 */
 		$genericFilters = array(
 			'Pattern' => array(
-								'filter_column' => 'string', 
-								'filter_pattern' => 'string',
+								'filter_column' 			=> array('string'), 
+								'filter_pattern' 			=> array('string'),
 						),
 			'ExcludeLowPopulation'	=> array(
-								'filter_excludelowpop' => 'string', 
-								'filter_excludelowpop_value' => 'float',
+								'filter_excludelowpop' 		=> array('string'), 
+								'filter_excludelowpop_value'=> array('float'),
 						),
 			'Sort' => array(
-								'filter_sort_column' => 'string', 
-								'filter_sort_order' => 'string',
+								'filter_sort_column' 		=> array('string', Piwik_Archive::INDEX_NB_VISITS),
+								'filter_sort_order' 		=> array('string', 'desc'),
 						),
 			'Limit' => array(
-								'filter_offset' 	=> 'integer',
-								'filter_limit' 		=> 'integer',
+								'filter_offset' 			=> array('integer'),
+								'filter_limit' 				=> array('integer'),
 						),
 		);
 		
@@ -133,10 +190,20 @@ class Piwik_API_Request
 			$filterParameters = array();
 			$exceptionRaised = false;
 			
-			foreach($parameters as $name => $type)
+			foreach($parameters as $name => $info)
 			{
+				// parameter type to cast to
+				$type = $info[0];
+				
+				// default value if specified, when the parameter doesn't have a value
+				$defaultValue = null;
+				if(isset($info[1]))
+				{
+					$defaultValue = $info[1];
+				}
+				
 				try {
-					$value = Piwik_Common::getRequestVar($name, null, null, $this->requestToUse);
+					$value = Piwik_Common::getRequestVar($name, $defaultValue, $type, $this->requestToUse);
 					settype($value, $type);
 					$filterParameters[] = $value;
 				}
diff --git a/modules/Access.php b/modules/Access.php
index 6de0673257..28c44103a9 100755
--- a/modules/Access.php
+++ b/modules/Access.php
@@ -138,4 +138,3 @@ class Piwik_Access
 	}
 }
 
-?>
\ No newline at end of file
diff --git a/modules/ArchiveProcessing.php b/modules/ArchiveProcessing.php
index 46b8628870..beac05210d 100644
--- a/modules/ArchiveProcessing.php
+++ b/modules/ArchiveProcessing.php
@@ -295,4 +295,4 @@ abstract class Piwik_ArchiveProcessing
 	}
 	
 }
-?>
+
diff --git a/modules/ArchiveProcessing/Day.php b/modules/ArchiveProcessing/Day.php
index 4e17c58fbd..a38e2dcb2c 100644
--- a/modules/ArchiveProcessing/Day.php
+++ b/modules/ArchiveProcessing/Day.php
@@ -1,4 +1,13 @@
 <?php
+/**
+ * Handles the archiving process for a day.
+ * The class provides generic methods to manipulate data from the DB, easily create Piwik_DataTable objects.
+ * 
+ * All the logic of the archiving is done inside the plugins listening to the event 'ArchiveProcessing_Day.compute'
+ * 
+ * @package Piwik_ArchiveProcessing
+ * 
+ */
 class Piwik_ArchiveProcessing_Day extends Piwik_ArchiveProcessing
 {
 	
@@ -181,4 +190,5 @@ class Piwik_ArchiveProcessing_Day extends Piwik_ArchiveProcessing
 		$oldRowToUpdate[Piwik_Archive::INDEX_BOUNCE_COUNT] 		+= $newRowToAdd[Piwik_Archive::INDEX_BOUNCE_COUNT];
 	}
 }
-?>
+
+
diff --git a/modules/ArchiveProcessing/Period.php b/modules/ArchiveProcessing/Period.php
index f08726daba..ce40097478 100644
--- a/modules/ArchiveProcessing/Period.php
+++ b/modules/ArchiveProcessing/Period.php
@@ -1,5 +1,7 @@
 <?php
-
+/**
+ * @package Piwik_ArchiveProcessing
+ */
 class Piwik_ArchiveProcessing_Period extends Piwik_ArchiveProcessing
 {
 	function __construct()
diff --git a/modules/ArchiveProcessing/Record.php b/modules/ArchiveProcessing/Record.php
index aa775025fd..fa65d6b6bf 100644
--- a/modules/ArchiveProcessing/Record.php
+++ b/modules/ArchiveProcessing/Record.php
@@ -1,5 +1,43 @@
 <?php
+/**
+ * A Record is a tuple (name, value) to be saved in the database.
+ * At its creation, the record registers itself to the RecordManager. 
+ * The record will then be automatically saved in the DB once the Archiving process is finished. 
+ * 
+ * We have two record types available:
+ * - numeric ; the value will be saved as float in the DB.
+ * 	 It should be used for INTEGER, FLOAT
+ * - blob ; the value will be saved in a binary field in the DB
+ * 	 It should be used for all the other types: PHP variables, STRING, serialized OBJECTS or ARRAYS, etc.
+ * 
+ * @package Piwik_ArchiveProcessing
+ * @subpackage Piwik_ArchiveProcessing_Record
+ */
+ 
+abstract class Piwik_ArchiveProcessing_Record
+{
+	public $name;
+	public $value;
+	
+	function __construct( $name, $value)
+	{
+		$this->name = $name;
+		$this->value = $value;
+		Piwik_ArchiveProcessing_Record_Manager::getInstance()->registerRecord($this);
+	}
+	public function delete()
+	{
+		Piwik_ArchiveProcessing_Record_Manager::getInstance()->unregister($this);
+	}
+	public function __destruct()
+	{
+	}
+}
 
+/**
+ * 
+ * @subpackage Piwik_ArchiveProcessing_Record
+ */
 class Piwik_ArchiveProcessing_Record_Manager
 {
 	protected $records = array();
@@ -17,16 +55,30 @@ class Piwik_ArchiveProcessing_Record_Manager
 		return self::$instance;
 	}
 
+	/**
+	 * Method called by Record objects to register themselves.
+	 * All records registered here will be saved in the DB at the end of the archiving process. 
+	 * @return void
+	 */
 	public function registerRecord( $record )
 	{
 		$this->records[$record->name] = $record;
 	}
 	
+	/**
+	 * Removes a record from the Record Manager.
+	 * 
+	 * @return void
+	 */
 	public function unregister( $deleteRecord )
 	{
 		unset($this->records[$deleteRecord->name]);
 	}
 	
+	/**
+	 * Returns a string containing the "name : value" of the record
+	 * @return string
+	 */
 	public function toString()
 	{
 		$str = '';
@@ -37,16 +89,26 @@ class Piwik_ArchiveProcessing_Record_Manager
 		return $str;
 	}
 	
+	/**
+	 * @return string
+	 */
 	public function __toString()
 	{
 		return $this->toString();
 	}
 	
+	/**
+	 * @return array of Records
+	 */
 	public function getRecords()
 	{
 		return $this->records;
 	}
 	
+	/**
+	 * Delete all records saved in the Manager.
+	 * @return void
+	 */
 	public function deleteAll()
 	{
 		foreach($this->records as $key => $record)
@@ -56,27 +118,13 @@ class Piwik_ArchiveProcessing_Record_Manager
 		$this->records = array();
 	}
 }
-
-abstract class Piwik_ArchiveProcessing_Record
-{
-	public $name;
-	public $value;
-	
-	function __construct( $name, $value)
-	{
-		$this->name = $name;
-		$this->value = $value;
-		Piwik_ArchiveProcessing_Record_Manager::getInstance()->registerRecord($this);
-	}
-	public function delete()
-	{
-		Piwik_ArchiveProcessing_Record_Manager::getInstance()->unregister($this);
-	}
-	public function __destruct()
-	{
-	}
-}
-
+ 
+/**
+ * Numeric record.
+ * Example: $record = new Piwik_ArchiveProcessing_Record_Numeric('nb_visitors_live', 15);
+ * 
+ * @subpackage Piwik_ArchiveProcessing_Record
+ */
 class Piwik_ArchiveProcessing_Record_Numeric extends Piwik_ArchiveProcessing_Record
 {	
 	function __construct( $name, $value)
@@ -90,7 +138,12 @@ class Piwik_ArchiveProcessing_Record_Numeric extends Piwik_ArchiveProcessing_Rec
 	}
 }
 
-
+/**
+ * Blob record.
+ * Example: $record = new Piwik_ArchiveProcessing_Record_Blob('visitor_names', serialize(array('piwik-fan', 'php', 'stevie-vibes')));
+ * The value will be compressed before being saved in the DB.
+ * @subpackage Piwik_ArchiveProcessing_Record
+ */
 class Piwik_ArchiveProcessing_Record_Blob extends Piwik_ArchiveProcessing_Record
 {
 	public $name;
@@ -107,6 +160,26 @@ class Piwik_ArchiveProcessing_Record_Blob extends Piwik_ArchiveProcessing_Record
 }
 
 
+/**
+ * Array of blob records.
+ * Useful for easily saving splited data in the DB.
+ *  
+ * Example: $record = new Piwik_ArchiveProcessing_Record_Blob_Array(
+ * 				'veryLongBook', 
+ * 				0 => serialize(	array( '1st chapter very long, 6MB of data we dont want to save' )),
+ * 				1 => serialize(	array( '2nd chapter very long, 8MB of data we dont want to save' )),
+ * 				2 => serialize(	array( '3rd chapter very long, 7MB of data we dont want to save' )),
+ * 				3 => serialize(	array( '4th chapter very long, 10MB of data we dont want to save' )),
+ * 		);
+ * 
+ * Will be saved in the DB as 
+ * 		veryLongBook   => X
+ * 		veryLongBook_1 => Y
+ * 		veryLongBook_2 => Z
+ * 		veryLongBook_3 => M
+ * 
+ * @subpackage Piwik_ArchiveProcessing_Record
+ */
 class Piwik_ArchiveProcessing_Record_Blob_Array extends Piwik_ArchiveProcessing_Record
 {
 	public $name;
@@ -137,8 +210,7 @@ class Piwik_ArchiveProcessing_Record_Blob_Array extends Piwik_ArchiveProcessing_
 	{
 		throw new Exception( 'Not valid' );
 	}
-	
 }
 
 
-?>
+
diff --git a/modules/Auth.php b/modules/Auth.php
index 982ec466bb..49cecc573d 100644
--- a/modules/Auth.php
+++ b/modules/Auth.php
@@ -43,4 +43,5 @@ class Piwik_Auth extends Zend_Auth_Adapter_DbTable
 	}
 	
 }
-?>
+
+
diff --git a/modules/Common.php b/modules/Common.php
index 152c177938..d4101569fb 100644
--- a/modules/Common.php
+++ b/modules/Common.php
@@ -522,4 +522,5 @@ class Piwik_Common
 	}
 	
 }
-?>
+
+
diff --git a/modules/Config.php b/modules/Config.php
index ef1861fc2b..ff31e16e56 100755
--- a/modules/Config.php
+++ b/modules/Config.php
@@ -28,4 +28,4 @@ class Piwik_Config extends Zend_Config_Ini
 		Zend_Registry::set('tablesPrefix', $this->database->tables_prefix);
 	}
 }
-?>
+
diff --git a/modules/DataFiles/Browsers.php b/modules/DataFiles/Browsers.php
index 842fadd891..53bdb89ec5 100644
--- a/modules/DataFiles/Browsers.php
+++ b/modules/DataFiles/Browsers.php
@@ -1,4 +1,9 @@
 <?php
+/**
+ * Browser list
+ * 
+ * @package Piwik_DataFiles
+ */
 if(!isset($GLOBALS['Piwik_BrowserList'] ))
 {
 	$GLOBALS['Piwik_BrowserList'] = array(
diff --git a/modules/DataFiles/Countries.php b/modules/DataFiles/Countries.php
index c0ba474657..38a0b48067 100644
--- a/modules/DataFiles/Countries.php
+++ b/modules/DataFiles/Countries.php
@@ -1,4 +1,9 @@
 <?php
+/**
+ * Country code and continent database
+ * 
+ * @package Piwik_DataFiles
+ */
 if(!isset($GLOBALS['Piwik_CountryList']))
 {
 	$GLOBALS['Piwik_CountryList'] = array(
@@ -222,4 +227,4 @@ if(!isset($GLOBALS['Piwik_CountryList']))
 			'zw' => array('afr'),
 		);
 }
-?>
+
diff --git a/modules/DataFiles/OS.php b/modules/DataFiles/OS.php
index 99517e91aa..b68eafb8cb 100644
--- a/modules/DataFiles/OS.php
+++ b/modules/DataFiles/OS.php
@@ -1,4 +1,9 @@
 <?php
+/**
+ * Operating systems database
+ * 
+ * @package Piwik_DataFiles
+ */
 if(!isset($GLOBALS['Piwik_Oslist']))
 {
 	$GLOBALS['Piwik_Oslist'] = array(
diff --git a/modules/DataFiles/SearchEngines.php b/modules/DataFiles/SearchEngines.php
index f88a8ad7d3..aa49183e5a 100644
--- a/modules/DataFiles/SearchEngines.php
+++ b/modules/DataFiles/SearchEngines.php
@@ -1,5 +1,20 @@
 <?php
-
+/**
+ * Search Engine database
+ * 
+ * Detail of a line:
+ * Url => array( SearchEngineName, VariableKeyword, [charset used by the search engine])
+ * 
+ * The main search engine URL has to be at the top of the list for the given search Engine.
+ * 
+ * You can add new search engines icons by adding the icon 
+ * in the plugins/Referers/images/SearchEngines directory 
+ * using the format "mainSearchEngineUrl.png". Example: www.google.com.png
+ *  
+ * Post your new search engines and logos in the forum, thank you for your help!
+ * 
+ * @package Piwik_DataFiles
+ */
 if(!isset($GLOBALS['Piwik_SearchEngines'] ))
 {
 	$GLOBALS['Piwik_SearchEngines'] = array(
@@ -1047,4 +1062,4 @@ if(!isset($GLOBALS['Piwik_SearchEngines'] ))
 	}
 	
 }
-?>
+
diff --git a/modules/DataTable.php b/modules/DataTable.php
index c0cb2c312c..c14a6040ed 100644
--- a/modules/DataTable.php
+++ b/modules/DataTable.php
@@ -527,4 +527,3 @@ function Piwik_DataTable_orderRowByLabel($o1,$o2)
  * 						[ keyword2, +1000% ]
  * 						[ keyword3, -430% ]
  */
-?>
\ No newline at end of file
diff --git a/modules/DataTable/Filter.php b/modules/DataTable/Filter.php
index d3a09464d2..11bc2ebf56 100644
--- a/modules/DataTable/Filter.php
+++ b/modules/DataTable/Filter.php
@@ -1,5 +1,18 @@
 <?php
-
+/**
+ * A filter is applied instantly to a given DataTable and can 
+ * - remove rows 
+ * - change columns values
+ * - add/remove columns or details
+ * - add/remove/edit sub DataTable associated to some rows
+ * - whatever your imagination wants :)
+ * 
+ * The concept is very simple: the filter is given the DataTable 
+ * and can do whatever is necessary on the data (in the filter() method).
+ * 
+ * @package Piwik_DataTable
+ * @subpackage Piwik_DataTable_Filter
+ */
 abstract class Piwik_DataTable_Filter
 {
 	protected $table;
@@ -16,13 +29,13 @@ abstract class Piwik_DataTable_Filter
 	abstract protected function filter();
 }
 
-require_once "DataTable/Filter/Limit.php";
-require_once "DataTable/Filter/Pattern.php";
-require_once "DataTable/Filter/Sort.php";
-require_once "DataTable/Filter/Empty.php";
 require_once "DataTable/Filter/ColumnCallback.php";
-require_once "DataTable/Filter/ColumnCallbackReplace.php";
 require_once "DataTable/Filter/ColumnCallbackAddDetail.php";
+require_once "DataTable/Filter/ColumnCallbackReplace.php";
 require_once "DataTable/Filter/DetailCallbackAddDetail.php";
+require_once "DataTable/Filter/Empty.php";
 require_once "DataTable/Filter/ExcludeLowPopulation.php";
+require_once "DataTable/Filter/Limit.php";
+require_once "DataTable/Filter/Pattern.php";
 require_once "DataTable/Filter/ReplaceColumnNames.php";
+require_once "DataTable/Filter/Sort.php";
diff --git a/modules/DataTable/Filter/ColumnCallback.php b/modules/DataTable/Filter/ColumnCallback.php
index 78ac773979..6c2bb12c82 100644
--- a/modules/DataTable/Filter/ColumnCallback.php
+++ b/modules/DataTable/Filter/ColumnCallback.php
@@ -1,7 +1,9 @@
 <?php
-
 /**
- * Delete all rows of when a given function returns false for a given column 
+ * Delete all rows of when a given function returns false for a given column.
+ * 
+ * @package Piwik_DataTable
+ * @subpackage Piwik_DataTable_Filter 
  */
 class Piwik_DataTable_Filter_ColumnCallback extends Piwik_DataTable_Filter
 {
diff --git a/modules/DataTable/Filter/ColumnCallbackAddDetail.php b/modules/DataTable/Filter/ColumnCallbackAddDetail.php
index 4668303f1f..742892b199 100644
--- a/modules/DataTable/Filter/ColumnCallbackAddDetail.php
+++ b/modules/DataTable/Filter/ColumnCallbackAddDetail.php
@@ -4,9 +4,14 @@
  * Add a new column to the table based on the value resulting 
  * from a callback function with the parameter being another column's value
  * 
- * For example from the "label" column we want to create a "short label" column
- * that is a shorter text.
+ * For example from the "label" column we can to create a "short label" column
+ * that is a shorter version of the label.
+ * 
+ * 
+ * @package Piwik_DataTable
+ * @subpackage Piwik_DataTable_Filter 
  */
+
 class Piwik_DataTable_Filter_ColumnCallbackAddDetail extends Piwik_DataTable_Filter
 {
 	private $columnToRead;
diff --git a/modules/DataTable/Filter/ColumnCallbackReplace.php b/modules/DataTable/Filter/ColumnCallbackReplace.php
index e52b54e320..76f0c0cc81 100644
--- a/modules/DataTable/Filter/ColumnCallbackReplace.php
+++ b/modules/DataTable/Filter/ColumnCallbackReplace.php
@@ -1,7 +1,10 @@
 <?php
-
 /**
- * Replace a column value with a new value resulting from the function call
+ * Replace a column value with a new value resulting 
+ * from the function called with the column's value
+ * 
+ * @package Piwik_DataTable
+ * @subpackage Piwik_DataTable_Filter 
  */
 class Piwik_DataTable_Filter_ColumnCallbackReplace extends Piwik_DataTable_Filter
 {
diff --git a/modules/DataTable/Filter/DetailCallbackAddDetail.php b/modules/DataTable/Filter/DetailCallbackAddDetail.php
index 67a53d0983..9c6b50fb6e 100644
--- a/modules/DataTable/Filter/DetailCallbackAddDetail.php
+++ b/modules/DataTable/Filter/DetailCallbackAddDetail.php
@@ -1,12 +1,14 @@
 <?php
-
 /**
  * Add a new detail to the table based on the value resulting 
  * from a callback function with the parameter being another detail's value
  * 
  * For example for the searchEngine we have a "details" information that gives 
  * the URL of the search engine. We use this URL to add a new "details" that gives 
- * the path of the logo for this search engine URL. 
+ * the path of the logo for this search engine URL (which has the format URL.png). 
+
+ * @package Piwik_DataTable
+ * @subpackage Piwik_DataTable_Filter 
  */
 class Piwik_DataTable_Filter_DetailCallbackAddDetail extends Piwik_DataTable_Filter
 {
diff --git a/modules/DataTable/Filter/Empty.php b/modules/DataTable/Filter/Empty.php
index 6e76a402da..a7462f11ca 100644
--- a/modules/DataTable/Filter/Empty.php
+++ b/modules/DataTable/Filter/Empty.php
@@ -1,5 +1,10 @@
 <?php
-
+/**
+ * Empty filter template.
+ * 
+ * @package Piwik_DataTable
+ * @subpackage Piwik_DataTable_Filter 
+ */
 class Piwik_DataTable_Filter_Empty extends Piwik_DataTable_Filter
 {
 	
@@ -16,4 +21,4 @@ class Piwik_DataTable_Filter_Empty extends Piwik_DataTable_Filter
 		}
 	}
 }
-?>
+
diff --git a/modules/DataTable/Filter/ExcludeLowPopulation.php b/modules/DataTable/Filter/ExcludeLowPopulation.php
index d7630ea1ed..efa63fcde7 100644
--- a/modules/DataTable/Filter/ExcludeLowPopulation.php
+++ b/modules/DataTable/Filter/ExcludeLowPopulation.php
@@ -1,4 +1,13 @@
 <?php
+/**
+ * Delete all rows that have a $columnToFilter value less than the $minimumValue 
+ * For example we delete from the countries report table all countries that have less than 3 visits.
+ * It is very useful to exclude noise from the reports.
+ * You can obviously apply this filter on a percentaged column, eg. remove all countries with the column 'percent_visits' less than 0.05
+ * 
+ * @package Piwik_DataTable
+ * @subpackage Piwik_DataTable_Filter 
+ */
 class Piwik_DataTable_Filter_ExcludeLowPopulation extends Piwik_DataTable_Filter
 {
 	static public $minimumValue;
@@ -27,4 +36,4 @@ class Piwik_DataTable_Filter_ExcludeLowPopulation extends Piwik_DataTable_Filter
 		return $value >= self::$minimumValue;
 	}
 }
-?>
+
diff --git a/modules/DataTable/Filter/Limit.php b/modules/DataTable/Filter/Limit.php
index 6ec00244a5..ec50762844 100644
--- a/modules/DataTable/Filter/Limit.php
+++ b/modules/DataTable/Filter/Limit.php
@@ -1,5 +1,10 @@
 <?php
-
+/**
+ * Delete all rows from the table that are not in the offset,offset+limit range
+ * 
+ * @package Piwik_DataTable
+ * @subpackage Piwik_DataTable_Filter 
+ */
 
 class Piwik_DataTable_Filter_Limit extends Piwik_DataTable_Filter
 {	
@@ -27,4 +32,4 @@ class Piwik_DataTable_Filter_Limit extends Piwik_DataTable_Filter
 	}
 }
 
-?>
+
diff --git a/modules/DataTable/Filter/Pattern.php b/modules/DataTable/Filter/Pattern.php
index 52c1ff46bf..849ddc5c36 100644
--- a/modules/DataTable/Filter/Pattern.php
+++ b/modules/DataTable/Filter/Pattern.php
@@ -1,5 +1,12 @@
 <?php
-
+/**
+ * Delete all rows for which the given $columnToFilter do not contain the $patternToSearch
+ * This filter is to be used on columns containing strings. 
+ * Exemple: fron the keyword report, keep only the rows for which the label contains "piwik"
+ * 
+ * @package Piwik_DataTable
+ * @subpackage Piwik_DataTable_Filter 
+ */
 class Piwik_DataTable_Filter_Pattern extends Piwik_DataTable_Filter
 {
 	private $columnToFilter;
@@ -24,4 +31,4 @@ class Piwik_DataTable_Filter_Pattern extends Piwik_DataTable_Filter
 		}
 	}
 }
-?>
+
diff --git a/modules/DataTable/Filter/ReplaceColumnNames.php b/modules/DataTable/Filter/ReplaceColumnNames.php
index 6309b16938..8ae60e50bb 100644
--- a/modules/DataTable/Filter/ReplaceColumnNames.php
+++ b/modules/DataTable/Filter/ReplaceColumnNames.php
@@ -1,7 +1,18 @@
 <?php
-
 /**
- * Delete all rows of when a given function returns false for a given column 
+ * This filter replaces column names using a mapping table that maps from the old name to the new name.
+ * 
+ * Why this filter?
+ * For saving bytes in the database, you can change all the columns labels by an integer value.
+ * Exemple instead of saving 10000 rows with the column name 'nb_unique_visitors' which would cost a lot of memory,
+ * we map it to the integer 1 before saving in the DB.
+ * After selecting the DataTable from the DB though, you need to restore back the real names so that
+ * it shows nicely in the report (XML for example).
+ * 
+ * You can specify the mapping array to apply in the constructor.
+ * 
+ * @package Piwik_DataTable
+ * @subpackage Piwik_DataTable_Filter 
  */
 class Piwik_DataTable_Filter_ReplaceColumnNames extends Piwik_DataTable_Filter
 {
@@ -16,7 +27,13 @@ class Piwik_DataTable_Filter_ReplaceColumnNames extends Piwik_DataTable_Filter
 				Piwik_Archive::INDEX_SUM_VISIT_LENGTH	=> 'sum_visit_length',
 				Piwik_Archive::INDEX_BOUNCE_COUNT		=> 'bounce_count',
 			);
-				
+	/**
+	 * @param DataTable Table
+	 * @param array Mapping to apply. Must have the format 	
+	 * 				array( 	OLD_COLUMN_NAME => NEW_COLUMN NAME,
+	 * 						OLD_COLUMN_NAME2 => NEW_COLUMN NAME2,
+	 * 					)
+	 */
 	public function __construct( $table, $mappingToApply = null )
 	{
 		parent::__construct($table);
diff --git a/modules/DataTable/Filter/Sort.php b/modules/DataTable/Filter/Sort.php
index a5c2463505..f4c6b24061 100644
--- a/modules/DataTable/Filter/Sort.php
+++ b/modules/DataTable/Filter/Sort.php
@@ -1,5 +1,10 @@
 <?php
-
+/**
+ * Sort the DataTable based on the value of column $columnToSort ordered by $order.
+ * 
+ * @package Piwik_DataTable
+ * @subpackage Piwik_DataTable_Filter 
+ */
 class Piwik_DataTable_Filter_Sort extends Piwik_DataTable_Filter
 {
 	private $columnToSort;
@@ -51,4 +56,4 @@ class Piwik_DataTable_Filter_Sort extends Piwik_DataTable_Filter
 		$this->table->sort( array($this,"sort") );
 	}
 }
-?>
+
diff --git a/modules/DataTable/Manager.php b/modules/DataTable/Manager.php
index cc93c61089..a7647d652d 100644
--- a/modules/DataTable/Manager.php
+++ b/modules/DataTable/Manager.php
@@ -1,5 +1,10 @@
 <?php
-
+/**
+ * The DataTable_Manager registers all the instanciated DataTable and provides an 
+ * easy way to access them.
+ * 
+ * @package Piwik_DataTable
+ */
 class Piwik_DataTable_Manager
 {
 	static private $instance = null;
@@ -19,14 +24,24 @@ class Piwik_DataTable_Manager
 	protected $tables = array();
 	protected $count = 0;
 	
-	function addTable( $table )
+	/**
+	 * Add a DataTable to the registry
+	 */
+	public function addTable( $table )
 	{
 		$this->tables[] = $table;
 		$this->count++;
 		return $this->count;
 	}
 	
-	function getTable( $idTable )
+	/**
+	 * Returns the DataTable associated to the ID $idTable.
+	 * NB: The datatable has to have been instanciated before! 
+	 * This method will not fetch the DataTable from the DB.
+	 * 
+	 * @exception If the table can't be found
+	 */
+	public function getTable( $idTable )
 	{
 		// the array tables is indexed at 0 
 		// but the index is computed as the count() of the array after inserting the table
@@ -40,15 +55,21 @@ class Piwik_DataTable_Manager
 		return $this->tables[$idTable];
 	}
 	
-	function deleteAll()
+	/**
+	 * Delete all the registered DataTables
+	 */
+	public function deleteAll()
 	{
 		Piwik::log("DELETE ALL ".$this->count()." TABLES");
 		$this->tables = array();
 	}
 	
+	/**
+	 * Returns the number of DataTable currently registered.
+	 */
 	function count()
 	{
 		return count($this->tables);
 	}
 }
-?>
+
diff --git a/modules/DataTable/Renderer.php b/modules/DataTable/Renderer.php
index a9a3a7412b..4e921d2386 100644
--- a/modules/DataTable/Renderer.php
+++ b/modules/DataTable/Renderer.php
@@ -1,6 +1,11 @@
 <?php
-
-class Piwik_DataTable_Renderer
+/**
+ * A DataTable Renderer can produce an output given a DataTable object.
+ * All new Renderers must be copied in DataTable/Renderer and added to the factory() method.
+ * 
+ * @package Piwik_DataTable
+ */
+abstract class Piwik_DataTable_Renderer
 {
 	protected $table;
 	
@@ -12,6 +17,22 @@ class Piwik_DataTable_Renderer
 		}
 	}
 	
+	/**
+	 * Computes the output and returns the string/binary
+	 */
+	abstract public function render();
+	
+	/**
+	 * @see render()
+	 */
+	public function __toString()
+	{
+		return $this->render();
+	}
+	
+	/**
+	 * Set the DataTable to be rendered
+	 */
 	public function setTable($table)
 	{
 		if(!($table instanceof Piwik_DataTable))
@@ -21,11 +42,10 @@ class Piwik_DataTable_Renderer
 		$this->table = $table;
 	}
 	
-	public function __toString()
-	{
-		return $this->render();
-	}
-	
+	/**
+	 * Returns the DataTable associated to the output format $name
+	 * @exception If the renderer is unknown
+	 */
 	static public function factory( $name )
 	{
 		$name = strtolower($name);
@@ -66,4 +86,4 @@ class Piwik_DataTable_Renderer
 	
 	
 }
-?>
+
diff --git a/modules/DataTable/Renderer/Console.php b/modules/DataTable/Renderer/Console.php
index 3375bb52fe..e6a4b82980 100644
--- a/modules/DataTable/Renderer/Console.php
+++ b/modules/DataTable/Renderer/Console.php
@@ -1,5 +1,10 @@
 <?php
-
+/**
+ * Simple output
+ * 
+ * @package Piwik_DataTable
+ * @subpackage Piwik_DataTable_Renderer
+ */
 class Piwik_DataTable_Renderer_Console extends Piwik_DataTable_Renderer
 {
 	protected $prefixRows;
@@ -65,4 +70,4 @@ class Piwik_DataTable_Renderer_Console extends Piwik_DataTable_Renderer
 	}	
 }
 
-?>
+
diff --git a/modules/DataTable/Renderer/HTML.php b/modules/DataTable/Renderer/HTML.php
index 0e27fc25bd..d948766710 100644
--- a/modules/DataTable/Renderer/HTML.php
+++ b/modules/DataTable/Renderer/HTML.php
@@ -1,5 +1,11 @@
 <?php
 
+/**
+ * Simple HTML output
+ * 
+ * @package Piwik_DataTable
+ * @subpackage Piwik_DataTable_Renderer
+ */
 class Piwik_DataTable_Renderer_HTML extends Piwik_DataTable_Renderer
 {
 	protected $prefixRows;
@@ -34,6 +40,7 @@ class Piwik_DataTable_Renderer_HTML extends Piwik_DataTable_Renderer
 		$allColumns = array();
 		foreach($table->getRows() as $row)
 		{
+			//TODO put that in a Simple_PHP filter that will make it easy as well to export in CSV
 			foreach($row->getColumns() as $column => $value)
 			{
 				$allColumns[$column] = true;
@@ -123,4 +130,5 @@ class Piwik_DataTable_Renderer_HTML extends Piwik_DataTable_Renderer
 	}	
 }
 
-?>
+
+
diff --git a/modules/DataTable/Renderer/PHP.php b/modules/DataTable/Renderer/PHP.php
index 228275fea0..3708431fe2 100644
--- a/modules/DataTable/Renderer/PHP.php
+++ b/modules/DataTable/Renderer/PHP.php
@@ -1,4 +1,12 @@
 <?php
+
+/**
+ * Returns the equivalent PHP array of the DataTable.
+ * You can specify in the constructor if you want the serialized version.
+ * 
+ * @package Piwik_DataTable
+ * @subpackage Piwik_DataTable_Renderer
+ */
 class Piwik_DataTable_Renderer_PHP extends Piwik_DataTable_Renderer
 {
 	protected $serialize;
diff --git a/modules/DataTable/Renderer/XML.php b/modules/DataTable/Renderer/XML.php
index 0d6ebef305..90f03f46af 100644
--- a/modules/DataTable/Renderer/XML.php
+++ b/modules/DataTable/Renderer/XML.php
@@ -1,5 +1,12 @@
 <?php
 
+/**
+ * XML export. Using the excellent Pear::XML_Serializer.
+ * We had to fix the PEAR library so that it works under PHP5 STRICT mode.
+ * 
+ * @package Piwik_DataTable
+ * @subpackage Piwik_DataTable_Renderer
+ */
 require_once "DataTable/Renderer/PHP.php";
 class Piwik_DataTable_Renderer_XML extends Piwik_DataTable_Renderer
 {
diff --git a/modules/DataTable/Row.php b/modules/DataTable/Row.php
index adc3c20665..8fac27225f 100644
--- a/modules/DataTable/Row.php
+++ b/modules/DataTable/Row.php
@@ -1,8 +1,18 @@
 <?php
 /**
- * IMPORTANT: A column named 'label' must not be composed only of the characters [0-9.]
- * Otherwise the methods to addDataTable, sumRow, etc. would fail because they would consider
- * the label as being a column to sum
+ * A DataTable is composed by rows.
+ * A row is composed by 
+ * - columns often at least a 'label' column containing the description 
+ * 		of the row, and some numeric values ('nb_visits', etc.)
+ * - details: other information never to be shown as "columns")
+ * - idSubtable: a row can be linked to a SubTable
+ * 
+ * IMPORTANT: Make sure that the column named 'label' contains at least one non-numeric character.
+ * Otherwise the method addDataTable() or sumRow() would fail because they would consider
+ * the 'label' as being a numeric column to sum.
+ * 
+ * @package Piwik_DataTable
+ * 
  */
 class Piwik_DataTable_Row
 {
@@ -52,6 +62,9 @@ class Piwik_DataTable_Row
 		}
 	}
 	
+	/**
+	 * When destroyed, a row destroys its associated subTable if there is one
+	 */
 	public function __destruct()
 	{
 		$idSubtable = $this->getIdSubDataTable();
@@ -61,6 +74,11 @@ class Piwik_DataTable_Row
 		}
 	}
 
+	/**
+	 * Returns the given column
+	 * @param string Column name
+	 * @return mixed|false The column value  
+	 */
 	public function getColumn( $name )
 	{
 		if(!isset($this->c[self::COLUMNS][$name]))
@@ -70,26 +88,51 @@ class Piwik_DataTable_Row
 		return $this->c[self::COLUMNS][$name];
 	}
 	
+	/**
+	 * Returns the given detail
+	 * @param string Detail name
+	 * @return mixed|false The detail value  
+	 */
+	public function getDetail( $name )
+	{
+		if(!isset($this->c[self::DETAILS][$name]))
+		{
+			return false;
+		}
+		return $this->c[self::DETAILS][$name];
+	}
+	
+	/**
+	 * Returns the array of columns
+	 * 
+	 * @return array array( 
+	 * 					'column1' 	=> VALUE,
+	 * 					'label' 	=> 'www.php.net'
+	 * 					'nb_visits' => 15894,
+	 * 			)
+	 */
 	public function getColumns()
 	{
 		return $this->c[self::COLUMNS];
 	}
 	
+	/**
+	 * Returns the array of details
+	 * 
+	 * @return array array( 
+	 * 					'logo' 	=> 'images/logo/www.google.png',
+	 * 					'url'	=> 'www.google.com'
+	 * 			)
+	 */
 	public function getDetails()
 	{	
 		return $this->c[self::DETAILS];
 	}
 	
-	public function getDetail( $name )
-	{
-		if(!isset($this->c[self::DETAILS][$name]))
-		{
-			return false;
-		}
-		return $this->c[self::DETAILS][$name];
-	}
-	
 	/**
+	 * Returns the ID of the subDataTable. 
+	 * If there is no such a table, returns null.
+	 * 
 	 * @return int|null
 	 */
 	public function getIdSubDataTable()
@@ -97,6 +140,12 @@ class Piwik_DataTable_Row
 		return $this->c[self::DATATABLE_ASSOCIATED];
 	}
 	
+	/**
+	 * Sums a DataTable to this row subDataTable.
+	 * If this row doesn't have a SubDataTable yet, we create a new one.
+	 * Then we add the values of the given DataTable to this row's DataTable 
+	 * @see addDataTable() for the summing algorithm 
+	 */
 	public function sumSubtable(Piwik_DataTable $subTable)
 	{
 		$thisSubtableID = $this->getIdSubDataTable();
@@ -113,15 +162,6 @@ class Piwik_DataTable_Row
 		$thisSubTable->addDataTable($subTable);
 	}
 
-	/**
-	 * Adds a subtable to a row. 
-	 * 
-	 */
-	public function addSubtable(Piwik_DataTable $subTable)
-	{
-		$this->checkNoSubTable();
-		$this->c[self::DATATABLE_ASSOCIATED] = $subTable->getId();
-	}
 	
 	protected function checkNoSubTable()
 	{
@@ -132,21 +172,51 @@ class Piwik_DataTable_Row
 	}
 	
 	
+	/**
+	 * Set a DataTable to be associated to this row.
+	 * If the row already has a DataTable associated to it, throws an Exception.
+	 * @throws Exception 
+	 * 
+	 */
+	public function addSubtable(Piwik_DataTable $subTable)
+	{
+		$this->checkNoSubTable();
+		$this->c[self::DATATABLE_ASSOCIATED] = $subTable->getId();
+	}
+	
+	/**
+	 * Set a DataTable to this row. If there is already 
+	 * a DataTable associated, it is simply overwritten.
+	 */
 	public function setSubtable(Piwik_DataTable $subTable)
 	{
 		$this->c[self::DATATABLE_ASSOCIATED] = $subTable->getId();
 	}
 	
+	/**
+	 * Set all the columns at once.
+	 * @param array array( 
+	 * 					'label' 	=> 'www.php.net'
+	 * 					'nb_visits' => 15894,
+	 * 			)
+	 */
 	public function setColumns( $columns )
 	{
 		$this->c[self::COLUMNS] = $columns;
 	}
 	
+	/**
+	 * Set the $value value to the column named $name
+	 */
 	public function setColumn($name, $value)
 	{
 		$this->c[self::COLUMNS][$name] = $value;
 	}
 	
+	/**
+	 * Add a new column to the row. If the column already exist, throw an exception
+	 * @throws Exception
+	 */
 	public function addColumn($name, $value)
 	{
 		if(isset($this->c[self::COLUMNS][$name]))
@@ -156,6 +226,11 @@ class Piwik_DataTable_Row
 		$this->c[self::COLUMNS][$name] = $value;
 	}
 	
+	
+	/**
+	 * Add a new detail to the row. If the column already exist, throw an exception
+	 * @throws Exception
+	 */
 	public function addDetail($name, $value)
 	{
 		if(isset($this->c[self::DETAILS][$name]))
@@ -192,8 +267,11 @@ class Piwik_DataTable_Row
 	
 	
 	/**
-	 *  2rows are equal is exact same columns / details
-	 * and if subtable is there then subtable has to be the same!
+	 * Helper function to test if two rows are equal.
+	 * 
+	 * Two rows are equal 
+	 * - if they have exactly the same columns / details
+	 * - if they have a subDataTable associated and that both of them are exactly the same.
 	 */
 	static public function isEqual( $row1, $row2 )
 	{		
@@ -240,4 +318,4 @@ class Piwik_DataTable_Row
 }
 
 require_once "Row/DataTableSummary.php";
-?>
+
diff --git a/modules/DataTable/Row/DataTableSummary.php b/modules/DataTable/Row/DataTableSummary.php
index 6881c6b8d6..0dceb67c8f 100644
--- a/modules/DataTable/Row/DataTableSummary.php
+++ b/modules/DataTable/Row/DataTableSummary.php
@@ -1,5 +1,15 @@
 <?php
-
+/**
+ * This class creates a row from a given DataTable. 
+ * The row contains 
+ * - for each numeric column, the resulting "summary" column is the sum of all the subRows
+ * - for every other column, it is ignored and will not be in the "summary row"
+ * 
+ * @see Piwik_DataTable_Row::sumRow() for more information on the algorith
+ * 
+ * @package Piwik_DataTable
+ * @subpackage Piwik_DataTable_Row
+ */
 class Piwik_DataTable_Row_DataTableSummary extends Piwik_DataTable_Row
 {
 	function __construct($subTable)
@@ -12,4 +22,4 @@ class Piwik_DataTable_Row_DataTableSummary extends Piwik_DataTable_Row
 		}
 	}
 }
-?>
+
diff --git a/modules/DataTable/Simple.php b/modules/DataTable/Simple.php
index 4c86186024..70cb79fa51 100644
--- a/modules/DataTable/Simple.php
+++ b/modules/DataTable/Simple.php
@@ -1,11 +1,34 @@
 <?php
+/**
+ * The DataTable_Simple is used to provide a very simple way to create simple DataGrid.
+ * 
+ * A DataTable Simple basically is an array of name => value 
+ * 
+ * Returning a DataTable_Simple from a plugin API Call has huge advantages:
+ * - the generic filters can be applied automatically (offset, limit, pattern search, sort, etc.)
+ * - the renderer can be applied (XML, PHP, HTML, etc.)
+ * 
+ * So you don't have to write specific renderer for your data, it is already available in all the formats supported natively by Piwik.
+ * 
+ * NB: A DataTable_Simple actually is a DataTable with 2 columns: 'label' and 'value'.
+ * 
+ * @package Piwik_DataTable
+ */
 class Piwik_DataTable_Simple extends Piwik_DataTable
 {
 	public function __construct()
 	{
 		parent::__construct();
 	}
-	
+
+	/**
+	 * Loads in the DataTable the array information
+	 * @param array Array containing the rows information
+	 * 		array(
+	 * 			'Label row 1' => Value row 1,
+	 * 			'Label row 2' => Value row 2,
+	 * 	)
+	 */	
 	function loadFromArray($array)
 	{
 		foreach($array as $label => $value)
@@ -17,4 +40,5 @@ class Piwik_DataTable_Simple extends Piwik_DataTable
 		}
 	}
 }
-?>
+
+
diff --git a/modules/Date.php b/modules/Date.php
index 507af231b3..0eec3c9206 100644
--- a/modules/Date.php
+++ b/modules/Date.php
@@ -42,4 +42,4 @@ class Piwik_Date extends Zend_Date
 		}
 	}
 }
-?>
+
diff --git a/modules/ErrorHandler.php b/modules/ErrorHandler.php
index 7ae1fc9d9d..76a562da8a 100755
--- a/modules/ErrorHandler.php
+++ b/modules/ErrorHandler.php
@@ -1,10 +1,10 @@
 <?php
 function Piwik_ErrorHandler($errno, $errstr, $errfile, $errline)
 {
-    ob_start();
-    debug_print_backtrace();
-    $backtrace = ob_get_contents();
-    ob_end_clean();
+//    ob_start();
+//    debug_print_backtrace();
+//    $backtrace = ob_get_contents();
+//    ob_end_clean();
     Zend_Registry::get('logger_error')->log($errno, $errstr, $errfile, $errline, $backtrace);
     
 	switch($errno)
@@ -31,4 +31,4 @@ function Piwik_ErrorHandler($errno, $errstr, $errfile, $errline)
 		break;
     }
 }
-?>
+
diff --git a/modules/ExceptionHandler.php b/modules/ExceptionHandler.php
index 62c2441534..9446ef02a0 100644
--- a/modules/ExceptionHandler.php
+++ b/modules/ExceptionHandler.php
@@ -15,4 +15,4 @@ function Piwik_ExceptionHandler(Exception $exception)
 		print("'" . $e->getMessage()."'");
 	}
 }
-?>
+
diff --git a/modules/Log.php b/modules/Log.php
index a5ea277e5a..b1b56363ac 100755
--- a/modules/Log.php
+++ b/modules/Log.php
@@ -125,4 +125,4 @@ class Piwik_Log_Formatter_FileFormatter implements Zend_Log_Formatter_Interface
 
 
 
-?>
+
diff --git a/modules/Log/APICall.php b/modules/Log/APICall.php
index 423760ded8..72574620d3 100644
--- a/modules/Log/APICall.php
+++ b/modules/Log/APICall.php
@@ -93,4 +93,4 @@ class Piwik_Log_Formatter_APICall_ScreenFormatter implements Zend_Log_Formatter_
 		
     }
 }
-?>
+
diff --git a/modules/Log/Error.php b/modules/Log/Error.php
index 138375de11..dfd3558937 100644
--- a/modules/Log/Error.php
+++ b/modules/Log/Error.php
@@ -84,4 +84,4 @@ class Piwik_Log_Formatter_Error_ScreenFormatter implements Zend_Log_Formatter_In
     }
 }
 
-?>
+
diff --git a/modules/Log/Exception.php b/modules/Log/Exception.php
index bc3b925cb8..189fe55407 100644
--- a/modules/Log/Exception.php
+++ b/modules/Log/Exception.php
@@ -64,4 +64,4 @@ class Piwik_Log_Formatter_Exception_ScreenFormatter implements Zend_Log_Formatte
 
 
 
-?>
+
diff --git a/modules/Log/Message.php b/modules/Log/Message.php
index 121b7cfd00..e9890ada59 100644
--- a/modules/Log/Message.php
+++ b/modules/Log/Message.php
@@ -48,4 +48,4 @@ class Piwik_Log_Formatter_Message_ScreenFormatter implements Zend_Log_Formatter_
     	}
     }
 }
-?>
+
diff --git a/modules/Log/Null.php b/modules/Log/Null.php
index a108c3d554..0f9e628f32 100644
--- a/modules/Log/Null.php
+++ b/modules/Log/Null.php
@@ -13,4 +13,4 @@ class Piwik_Log_Null extends Zend_Log
 	}
 }
 
-?>
+
diff --git a/modules/LogStats.php b/modules/LogStats.php
index ef10f58285..d603366f08 100644
--- a/modules/LogStats.php
+++ b/modules/LogStats.php
@@ -202,4 +202,4 @@ function printDebug( $info = '' )
 		}
 	}
 }
-?>
+
diff --git a/modules/LogStats/Action.php b/modules/LogStats/Action.php
index fad520f6e2..7c10d8abc5 100644
--- a/modules/LogStats/Action.php
+++ b/modules/LogStats/Action.php
@@ -219,4 +219,4 @@ class Piwik_LogStats_Action
 	 }
 }
 
-?>
+
diff --git a/modules/LogStats/Config.php b/modules/LogStats/Config.php
index bd486ac519..1a25ef22d3 100644
--- a/modules/LogStats/Config.php
+++ b/modules/LogStats/Config.php
@@ -38,4 +38,4 @@ class Piwik_LogStats_Config
 	}
 }
 
-?>
+
diff --git a/modules/LogStats/Cookie.php b/modules/LogStats/Cookie.php
index b682fdc037..0b095a4c4e 100644
--- a/modules/LogStats/Cookie.php
+++ b/modules/LogStats/Cookie.php
@@ -221,4 +221,4 @@ class Piwik_LogStats_Cookie
 //$c->save();
 //$c->deleteCookie();
 
-?>
+
diff --git a/modules/LogStats/Db.php b/modules/LogStats/Db.php
index 25f09d8784..6cd9e70287 100644
--- a/modules/LogStats/Db.php
+++ b/modules/LogStats/Db.php
@@ -123,4 +123,5 @@ class Piwik_LogStats_Db
 		}
 	}
 }
-?>
+
+
diff --git a/modules/LogStats/Generator.php b/modules/LogStats/Generator.php
index 090434a8a8..4871c899a9 100644
--- a/modules/LogStats/Generator.php
+++ b/modules/LogStats/Generator.php
@@ -461,4 +461,4 @@ class Piwik_LogStats_Generator_Visit extends Piwik_LogStats_Visit
 	}
 	
 }
-?>
+
diff --git a/modules/LogStats/Visit.php b/modules/LogStats/Visit.php
index d42faee6d4..5e3537135b 100644
--- a/modules/LogStats/Visit.php
+++ b/modules/LogStats/Visit.php
@@ -738,4 +738,4 @@ class Piwik_LogStats_Visit
 	}
 		
 }
-?>
+
diff --git a/modules/Period.php b/modules/Period.php
index 53b7a570b7..f3082d2014 100644
--- a/modules/Period.php
+++ b/modules/Period.php
@@ -344,7 +344,3 @@ class Piwik_Period_Year extends Piwik_Period
 	}
 }
 
-
-
-
-?>
diff --git a/modules/Piwik.php b/modules/Piwik.php
index 96a33bde85..4a7984fc3a 100755
--- a/modules/Piwik.php
+++ b/modules/Piwik.php
@@ -516,4 +516,4 @@ class Piwik
 		$db->query( "DROP TABLE IF EXISTS ". implode(", ", self::getTablesNames()) );
 	}
 }
-?>
+
diff --git a/modules/Plugin.php b/modules/Plugin.php
index d9b72adbd0..057bdc26bb 100644
--- a/modules/Plugin.php
+++ b/modules/Plugin.php
@@ -84,4 +84,4 @@ abstract class Piwik_Plugin
 		return;
 	}
 }
-?>
+
diff --git a/modules/PluginsManager.php b/modules/PluginsManager.php
index bf7caeca8f..090f4cc7f2 100644
--- a/modules/PluginsManager.php
+++ b/modules/PluginsManager.php
@@ -167,4 +167,3 @@ function Piwik_PostEvent( $eventName, $object = null, $info = array() )
 }
 
 
-?>
diff --git a/modules/Site.php b/modules/Site.php
index 06b7043f81..aa892465bf 100644
--- a/modules/Site.php
+++ b/modules/Site.php
@@ -12,4 +12,4 @@ class Piwik_Site
 		return $this->id;
 	}
 }
-?>
+
diff --git a/modules/SitesManager.php b/modules/SitesManager.php
index 6064e04009..d6bac0a111 100755
--- a/modules/SitesManager.php
+++ b/modules/SitesManager.php
@@ -2,7 +2,7 @@
 
 require_once "API/APIable.php";
 
-class Piwik_SitesManager_API extends Piwik_APIable
+class Piwik_SitesManager_API extends Piwik_Apiable
 {
 	static private $instance = null;
 	protected function __construct()
@@ -450,4 +450,4 @@ class Piwik_SitesManager_API extends Piwik_APIable
 		return $aUrls;
 	}
 }
-?>
+
diff --git a/modules/TablePartitioning.php b/modules/TablePartitioning.php
index 081849896b..59a1d91771 100644
--- a/modules/TablePartitioning.php
+++ b/modules/TablePartitioning.php
@@ -98,4 +98,4 @@ class Piwik_TablePartitioning_Daily extends Piwik_TablePartitioning
 	}
 		
 }
-?>
+
diff --git a/modules/Timer.php b/modules/Timer.php
index fcbc9043a0..d26a8cef07 100644
--- a/modules/Timer.php
+++ b/modules/Timer.php
@@ -34,4 +34,3 @@ class Piwik_Timer
     	return "Time elapsed: ". $this->getTime() ."s";
     }
 }
-?>
\ No newline at end of file
diff --git a/modules/Translate.php b/modules/Translate.php
index 3c8e7706dd..47a09fc1cf 100644
--- a/modules/Translate.php
+++ b/modules/Translate.php
@@ -49,4 +49,4 @@ function Piwik_Translate($index)
 	}
 	throw new Exception("Translation string '$index' not available.");
 }
-?>
+
diff --git a/modules/UsersManager.php b/modules/UsersManager.php
index c6d7a90a8c..769f8ac00e 100755
--- a/modules/UsersManager.php
+++ b/modules/UsersManager.php
@@ -1,7 +1,7 @@
 <?php
 Zend_Loader::loadClass("Piwik_Access");
 
-class Piwik_UsersManager_API extends Piwik_APIable
+class Piwik_UsersManager_API extends Piwik_Apiable
 {
 	static private $instance = null;
 	protected function __construct()