phpdoc cleanup:

 * add @category (Piwik => 'core', Piwik_Plugins => 'plugins')
 * in core, use @package and @subpackage more consistently to group files/classes; exception is DataFiles/*, PluginsFunctions/*, and SmartyPlugins/*
 * in plugins, @package is the plugin name
 * removed '@param none' -- not a phpdoc convention
 * '@throws' and '@return void' are also not phpdoc conventions, but are widely used elsewhere, e.g., Smarty & Zend


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

core/API/DataTableGenericFilter.php

@@ -6,9 +6,14 @@
  * @license http://www.gnu.org/licenses/gpl-3.0.html Gpl v3 or later
  * @version $Id$
  * 
- * @package Piwik_API
+ * @category Piwik
+ * @package Piwik
  */
 
+/**
+ * @package Piwik
+ * @subpackage Piwik_API
+ */
 class Piwik_API_DataTableGenericFilter
 {
 	function __construct( $datatable, $request )
@@ -73,7 +78,6 @@ class Piwik_API_DataTableGenericFilter
 	 * Disable this feature by setting the parameter disable_generic_filters to 1 in the API call request.
 	 * 
 	 * @param Piwik_DataTable
-	 * @return void
 	 */
 	protected function applyGenericFilters($datatable)
 	{

core/API/DocumentationGenerator.php

@@ -6,9 +6,14 @@
  * @license http://www.gnu.org/licenses/gpl-3.0.html Gpl v3 or later
  * @version $Id$
  * 
- * @package Piwik_API
+ * @category Piwik
+ * @package Piwik
  */
 
+/**
+ * @package Piwik
+ * @subpackage Piwik_API
+ */
 class Piwik_API_DocumentationGenerator
 {
 	protected $countPluginsLoaded = 0;
@@ -193,6 +198,5 @@ class Piwik_API_DocumentationGenerator
 		}
 		$sParameters = implode(", ", $asParameters);
 		return "($sParameters)";
-	}
-	
+	}	
 }

core/API/Proxy.php

@@ -6,7 +6,8 @@
  * @license http://www.gnu.org/licenses/gpl-3.0.html Gpl v3 or later
  * @version $Id$
  * 
- * @package Piwik_API
+ * @category Piwik
+ * @package Piwik
  */
 
 /**
@@ -17,7 +18,8 @@
  * 
  * It will also log the performance of API calls (time spent, parameter values, etc.) if logger available
  * 
- * @package Piwik_API
+ * @package Piwik
+ * @subpackage Piwik_API
  */
 class Piwik_API_Proxy
 {

core/API/Request.php

@@ -6,8 +6,8 @@
  * @license http://www.gnu.org/licenses/gpl-3.0.html Gpl v3 or later
  * @version $Id$
  * 
- * 
- * @package Piwik_API
+ * @category Piwik
+ * @package Piwik
  */
 
 /**
@@ -33,7 +33,8 @@
  *  echo $result;
  * 
  * @see http://dev.piwik.org/trac/wiki/API
- * @package Piwik_API
+ * @package Piwik
+ * @subpackage Piwik_API
  */
 class Piwik_API_Request
 {	

core/API/ResponseBuilder.php

@@ -6,9 +6,14 @@
  * @license http://www.gnu.org/licenses/gpl-3.0.html Gpl v3 or later
  * @version $Id$
  * 
- * @package Piwik_API
+ * @category Piwik
+ * @package Piwik
  */
 
+/**
+ * @package Piwik
+ * @subpackage Piwik_API
+ */
 class Piwik_API_ResponseBuilder
 {
 	private $request = null;

core/Access.php

@@ -6,8 +6,8 @@
  * @license http://www.gnu.org/licenses/gpl-3.0.html Gpl v3 or later
  * @version $Id$
  *
+ * @category Piwik
  * @package Piwik
- *
  */
 
 /**
@@ -33,6 +33,7 @@
  * and he only can change the main configuration settings.
  *
  * @package Piwik
+ * @subpackage Piwik_Access
  */
 class Piwik_Access
 {	
@@ -155,7 +156,12 @@ class Piwik_Access
 		}
 		return true;
 	}
-	
+
+	/**
+	 * Reload super user access
+	 *
+	 * @return bool
+	 */	
 	protected function reloadAccessSuperUser()
 	{
 		$this->isSuperUser = true;
@@ -166,8 +172,6 @@ class Piwik_Access
 	/**
 	 * We bypass the normal auth method and give the current user Super User rights.
 	 * This should be very carefully used.
-	 * 
-	 * @return void
 	 */
 	public function setSuperUser()
 	{
@@ -186,6 +190,7 @@ class Piwik_Access
 	
 	/**
 	 * Returns the current user login
+	 *
 	 * @return string|null
 	 */
 	public function getLogin()
@@ -195,6 +200,7 @@ class Piwik_Access
 
 	/**
 	 * Returns the token_auth used to authenticate this user in the API
+	 *
 	 * @return string|null
 	 */
 	public function getTokenAuth()
@@ -261,6 +267,7 @@ class Piwik_Access
 
 	/**
 	 * If the user doesn't have an ADMIN access for at least one website, throws an exception
+	 *
 	 * @throws Exception
 	 */
 	public function checkUserHasSomeAdminAccess()
@@ -274,6 +281,7 @@ class Piwik_Access
 	
 	/**
 	 * If the user doesn't have any view permission, throw exception
+	 *
 	 * @throws Exception
 	 */
 	public function checkUserHasSomeViewAccess()
@@ -347,6 +355,7 @@ class Piwik_Access
  * Exception thrown when a user doesn't  have sufficient access.
  * 
  * @package Piwik
+ * @subpackage Piwik_Access
  */
 class Piwik_Access_NoAccessException extends Exception
 {}

core/Archive.php

@@ -6,6 +6,7 @@
  * @license http://www.gnu.org/licenses/gpl-3.0.html Gpl v3 or later
  * @version $Id$
  * 
+ * @category Piwik
  * @package Piwik
  */
 

core/Archive/Array.php

@@ -6,14 +6,16 @@
  * @license http://www.gnu.org/licenses/gpl-3.0.html Gpl v3 or later
  * @version $Id$
  * 
- * 
- * @package Piwik_Archive
+ * @category Piwik
+ * @package Piwik
  */
 
 /**
  * Piwik_Archive_Array is used to store multiple archives, 
  * for example one archive for a given day for each Piwik website
  *
+ * @package Piwik
+ * @subpackage Piwik_Archive
  */
 abstract class Piwik_Archive_Array extends Piwik_Archive
 {	

core/Archive/Array/IndexedByDate.php

@@ -6,9 +6,14 @@
  * @license http://www.gnu.org/licenses/gpl-3.0.html Gpl v3 or later
  * @version $Id$
  * 
- * @package Piwik_Archive
+ * @category Piwik
+ * @package Piwik
  */
 
+/**
+ * @package Piwik
+ * @subpackage Piwik_Archive
+ */
 class Piwik_Archive_Array_IndexedByDate extends Piwik_Archive_Array 
 {
 	/**

core/Archive/Array/IndexedBySite.php

@@ -6,9 +6,14 @@
  * @license http://www.gnu.org/licenses/gpl-3.0.html Gpl v3 or later
  * @version $Id$
  * 
- * @package Piwik_Archive
+ * @category Piwik
+ * @package Piwik
  */
 
+/**
+ * @package Piwik
+ * @subpackage Piwik_Archive
+ */
 class Piwik_Archive_Array_IndexedBySite extends Piwik_Archive_Array 
 {
 	/**

core/Archive/Single.php

@@ -7,13 +7,16 @@
  * @version $Id$
  * 
  * 
- * @package Piwik_Archive
+ * @category Piwik
+ * @package Piwik
  */
 
 /**
  * Piwik_Archive_Single is used to store the data of a single archive, 
  * for example the statistics for the 'day' '2008-02-21' for the website idSite '2' 
  *
+ * @package Piwik
+ * @subpackage Piwik_Archive
  */
 class Piwik_Archive_Single extends Piwik_Archive
 {
@@ -141,8 +144,6 @@ class Piwik_Archive_Single extends Piwik_Archive
 	 * Prepares the archive. Gets the idarchive from the ArchiveProcessing.
 	 * 
 	 * This will possibly launch the archiving process if the archive was not available.
-	 * 
-	 * @return void
 	 */
 	public function prepareArchive()
 	{
@@ -278,8 +279,6 @@ class Piwik_Archive_Single extends Piwik_Archive
 	 * @param string $name
 	 * @param Piwik_DataTable $dataTableToLoad
 	 * @param bool $addMetadataSubtableId
-	 * 
-	 * @return void
 	 */
 	public function loadSubDataTables($name, Piwik_DataTable $dataTableToLoad, $addMetadataSubtableId = false)
 	{
@@ -310,8 +309,6 @@ class Piwik_Archive_Single extends Piwik_Archive
 	
 	/**
 	 * Free the blob cache memory array
-	 *
-	 * @return void
 	 */
 	public function freeBlob( $name )
 	{
@@ -322,7 +319,7 @@ class Piwik_Archive_Single extends Piwik_Archive
 	/**
 	 * Fetches all blob fields name_* at once for the current archive for performance reasons.
 	 * 
-	 * @return void
+	 * @return false if no visits
 	 */
 	public function preFetchBlob( $name )
 	{

core/ArchiveProcessing.php

@@ -6,7 +6,8 @@
  * @license http://www.gnu.org/licenses/gpl-3.0.html Gpl v3 or later
  * @version $Id$
  * 
- * @package Piwik_ArchiveProcessing
+ * @category Piwik
+ * @package Piwik
  */
 
 /**
@@ -25,7 +26,8 @@
  * - name 		= the name of the report (ex: uniq_visitors or search_keywords_by_search_engines)
  * - value 		= the actual data
  * 
- * @package Piwik_ArchiveProcessing
+ * @package Piwik
+ * @subpackage Piwik_ArchiveProcessing
  */
 abstract class Piwik_ArchiveProcessing
 {
@@ -216,8 +218,6 @@ abstract class Piwik_ArchiveProcessing
 	
 	/**
 	 * Inits the object
-	 * 
-	 * @return void
 	 */
 	protected function loadArchiveProperties()
 	{		
@@ -312,8 +312,6 @@ abstract class Piwik_ArchiveProcessing
 	
 	/**
 	 * Init the object before launching the real archive processing
-	 * 
-	 * @return void
 	 */
 	protected function initCompute()
 	{
@@ -330,8 +328,6 @@ abstract class Piwik_ArchiveProcessing
 	 * Makes sure the new archive is marked as "successful" in the DB
 	 * 
 	 * We also try to delete some stuff from memory but really there is still a lot...
-	 * 
-	 * @return void
 	 */
 	protected function postCompute()
 	{

core/ArchiveProcessing/Day.php

@@ -6,7 +6,8 @@
  * @license http://www.gnu.org/licenses/gpl-3.0.html Gpl v3 or later
  * @version $Id$
  * 
- * @package Piwik_ArchiveProcessing
+ * @category Piwik
+ * @package Piwik
  */
 
 /**
@@ -16,8 +17,8 @@
  * 
  * All the logic of the archiving is done inside the plugins listening to the event 'ArchiveProcessing_Day.compute'
  * 
- * @package Piwik_ArchiveProcessing
- * 
+ * @package Piwik
+ * @subpackage Piwik_ArchiveProcessing
  */
 class Piwik_ArchiveProcessing_Day extends Piwik_ArchiveProcessing
 {
@@ -32,8 +33,6 @@ class Piwik_ArchiveProcessing_Day extends Piwik_ArchiveProcessing
 	 * Main method to process logs for a day. The only logic done here is computing the number of visits, actions, etc.
 	 * All the other reports are computed inside plugins listening to the event 'ArchiveProcessing_Day.compute'.
 	 * See some of the plugins for an example eg. 'Provider'
-	 * 
-	 * @return void
 	 */
 	protected function compute()
 	{
@@ -372,8 +371,8 @@ class Piwik_ArchiveProcessing_Day extends Piwik_ArchiveProcessing
 	 * 			LABEL2 => array( Piwik_Archive::INDEX_NB_VISITS => Y, [...] )
 	 * 			);
 	 * 		)
-	 * @param array by reference, will be modified
-	 * @return void (array by reference is modified)
+	 *
+	 * @param array $interestByLabel Passed by reference, will be modified
 	 */
 	function enrichConversionsByLabelArray(&$interestByLabel)
 	{
@@ -394,8 +393,7 @@ class Piwik_ArchiveProcessing_Day extends Piwik_ArchiveProcessing
 	}
 
 	/**
-	 * @param array $interestByLabelAndSubLabel
-	 * @return void (array by reference is modified)
+	 * @param array $interestByLabelAndSubLabel Passed by reference, will be modified
 	 */
 	function enrichConversionsByLabelArrayHasTwoLevels(&$interestByLabelAndSubLabel)
 	{

core/ArchiveProcessing/Period.php

@@ -6,7 +6,8 @@
  * @license http://www.gnu.org/licenses/gpl-3.0.html Gpl v3 or later
  * @version $Id$
  * 
- * @package Piwik_ArchiveProcessing
+ * @category Piwik
+ * @package Piwik
  */
 
 /**
@@ -17,7 +18,8 @@
  * These methods are called by the plugins that do the logic of archiving their own data. \
  * They hook on the event 'ArchiveProcessing_Period.compute'
  * 
- * @package Piwik_ArchiveProcessing
+ * @package Piwik
+ * @subpackage Piwik_ArchiveProcessing
  */
 class Piwik_ArchiveProcessing_Period extends Piwik_ArchiveProcessing
 {
@@ -253,8 +255,6 @@ class Piwik_ArchiveProcessing_Period extends Piwik_ArchiveProcessing
 	 * 
 	 * All the other reports are computed inside plugins listening to the event 'ArchiveProcessing_Period.compute'.
 	 * See some of the plugins for an example.
-	 * 
-	 * @return void
 	 */
 	protected function compute()
 	{		
@@ -292,8 +292,6 @@ class Piwik_ArchiveProcessing_Period extends Piwik_ArchiveProcessing
 	/**
 	 * Called at the end of the archiving process.
 	 * Does some cleaning job in the database.
-	 * 
-	 * @return void
 	 */
 	protected function postCompute()
 	{

core/ArchiveProcessing/Record.php

@@ -6,7 +6,8 @@
  * @license http://www.gnu.org/licenses/gpl-3.0.html Gpl v3 or later
  * @version $Id$
  * 
- * @package Piwik_ArchiveProcessing
+ * @category Piwik
+ * @package Piwik
  */
 
 /**
@@ -20,8 +21,8 @@
  * - 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
+ * @package Piwik
+ * @subpackage Piwik_ArchiveProcessing
  */
 abstract class Piwik_ArchiveProcessing_Record
 {

core/ArchiveProcessing/Record/Blob.php

@@ -6,7 +6,8 @@
  * @license http://www.gnu.org/licenses/gpl-3.0.html Gpl v3 or later
  * @version $Id$
  * 
- * @package Piwik_ArchiveProcessing
+ * @category Piwik
+ * @package Piwik
  */
 
 /**
@@ -14,8 +15,8 @@
  * 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.
  * 
- * @package Piwik_ArchiveProcessing
- * @subpackage Piwik_ArchiveProcessing_Record
+ * @package Piwik
+ * @subpackage Piwik_ArchiveProcessing
  */
 class Piwik_ArchiveProcessing_Record_Blob extends Piwik_ArchiveProcessing_Record
 {

core/ArchiveProcessing/Record/Numeric.php

@@ -6,15 +6,16 @@
  * @license http://www.gnu.org/licenses/gpl-3.0.html Gpl v3 or later
  * @version $Id$
  * 
- * @package Piwik_ArchiveProcessing
+ * @category Piwik
+ * @package Piwik
  */
 
 /**
  * Numeric record.
  * Example: $record = new Piwik_ArchiveProcessing_Record_Numeric('nb_visitors_live', 15);
  * 
- * @package Piwik_ArchiveProcessing
- * @subpackage Piwik_ArchiveProcessing_Record
+ * @package Piwik
+ * @subpackage Piwik_ArchiveProcessing
  */
 class Piwik_ArchiveProcessing_Record_Numeric extends Piwik_ArchiveProcessing_Record
 {	

core/ArchiveProcessing/RecordArray.php

@@ -6,7 +6,8 @@
  * @license http://www.gnu.org/licenses/gpl-3.0.html Gpl v3 or later
  * @version $Id$
  * 
- * @package Piwik_ArchiveProcessing
+ * @category Piwik
+ * @package Piwik
  */
 
 /**
@@ -27,8 +28,8 @@
  * 		veryLongBook_2 => Z
  * 		veryLongBook_3 => M
  * 
- * @package Piwik_ArchiveProcessing
- * @subpackage Piwik_ArchiveProcessing_Record
+ * @package Piwik
+ * @subpackage Piwik_ArchiveProcessing
  */
 class Piwik_ArchiveProcessing_RecordArray extends Piwik_ArchiveProcessing_Record
 {

core/Auth.php

@@ -6,9 +6,16 @@
  * @license http://www.gnu.org/licenses/gpl-3.0.html Gpl v3 or later
  * @version $Id$
  *
+ * @category Piwik
  * @package Piwik
  */
 
+/**
+ * Interface for authentication modules
+ *
+ * @package Piwik
+ * @subpackage Piwik_Auth
+ */
 interface Piwik_Auth {
 	/**
 	 * Authentication module's name, e.g., "Login"
@@ -24,8 +31,11 @@ interface Piwik_Auth {
 }
 
 /**
+ * Authentication result
  *
+ * @see Zend_Auth_Result
  * @package Piwik
+ * @subpackage Piwik_Auth
  */
 class Piwik_Auth_Result extends Zend_Auth_Result
 {
@@ -37,7 +47,15 @@ class Piwik_Auth_Result extends Zend_Auth_Result
 	protected $_token_auth = null;
 	
 	const SUCCESS_SUPERUSER_AUTH_CODE = 42;
-	
+
+	/**
+	 * Constructor for Piwik_Auth_Result
+	 *
+	 * @param int $code
+	 * @param string $login identity
+	 * @param string $token_auth
+	 * @param array $messages
+	 */
 	public function __construct($code, $login, $token_auth, array $messages = array())
 	{
 		// Piwik_Auth_Result::SUCCESS_SUPERUSER_AUTH_CODE, Piwik_Auth_Result::SUCCESS, Piwik_Auth_Result::FAILURE  

core/CacheFile.php

@@ -6,6 +6,7 @@
  * @license http://www.gnu.org/licenses/gpl-3.0.html Gpl v3 or later
  * @version $Id$
  * 
+ * @category Piwik
  * @package Piwik
  */
 
@@ -16,6 +17,8 @@
  *
  * We may want to add support for cache expire, storing last modification time in the file. See code in:
  * - openx/lib/max/Delivery/cache.php
+ *
+ * @package Piwik
  */
 class Piwik_CacheFile
 {