Fixes #1478

 * Adding one sentence to one paragraph description of each API (feedback on the actual test is most welcome!)
 * This will be displayed on the API Reference page: http://piwik.org/docs/analytics-api/reference/ 
that's why it's pretty important :)
 * Adding table of contents in the API Page

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

24 files changed, 172 insertions, 53 deletions

diff --git a/plugins/API/API.php b/plugins/API/API.php
index 705ee6742b..b227d4af30 100644
--- a/plugins/API/API.php
+++ b/plugins/API/API.php
@@ -12,7 +12,6 @@
  */
 
 /**
- * 
  * @package Piwik_API
  */
 class Piwik_API extends Piwik_Plugin {
@@ -46,6 +45,19 @@ class Piwik_API extends Piwik_Plugin {
 
 
 /**
+ * This API is the <a href='http://piwik.org/docs/analytics-api/metadata/' target='_blank'>Metadata API</a>: it gives information about all other available APIs methods, as well as providing
+ * human readable and more complete outputs than normal API methods. 
+ * 
+ * Some of the information that is returned by the Metadata API: 
+ * <ul>
+ * <li>the dynamically generated list of all API methods via "getReportMetadata"</li> 
+ * <li>the list of metrics that will be returned by each method, along with their human readable name, via "getDefaultMetrics" and "getDefaultProcessedMetrics"</li>
+ * <li>the list of segments metadata supported by all functions that have a 'segment' parameter</li>
+ * <li>the (truly magic) method "getProcessedReport" will return a human readable version of any other report, and include the processed metrics such as 
+ * conversion rate, time on site, etc. which are not directly available in other methods.  
+ * </ul>
+ * The Metadata API is for example used by the Piwik Mobile App to automatically display all Piwik reports, with translated report & columns names and nicely formatted values.
+ * More information on the <a href='http://piwik.org/docs/analytics-api/metadata/' target='_blank'>Metadata API documentation page</a>
  * 
  * @package Piwik_API
  */
diff --git a/plugins/API/css/styles.css b/plugins/API/css/styles.css
index 3b52ba995a..ca78a2ae8b 100644
--- a/plugins/API/css/styles.css
+++ b/plugins/API/css/styles.css
@@ -27,3 +27,20 @@
 	line-height:140%;
 	padding-bottom:20px;
 }
+
+.apiFirstLine {
+	font-weight:bold;
+	padding-bottom:10px;
+}
+.page_api ul {
+    list-style: disc outside none;
+    margin-left: 25px;
+}
+.apiDescription {
+	line-height:1.5em;
+	padding-bottom:1em;
+}
+.apiMethod {
+	margin-bottom:5px;
+	margin-left:20px;
+}
\ No newline at end of file
diff --git a/plugins/API/templates/listAllAPI.tpl b/plugins/API/templates/listAllAPI.tpl
index 65a8356277..b2f19fd04a 100644
--- a/plugins/API/templates/listAllAPI.tpl
+++ b/plugins/API/templates/listAllAPI.tpl
@@ -19,10 +19,10 @@
     
     <h2>{'API_UserAuthentication'|translate}</h2>
     <p>
-    {'API_UsingTokenAuth'|translate:'<b>':'</b>':"<u><code>&amp;token_auth=$token_auth</code></u>"}<br />
-    <span id='token_auth'>token_auth = <b>{$token_auth}</b></span><br />
+    {'API_UsingTokenAuth'|translate:'<b>':'</b>':""}<br />
+    <span id='token_auth'>&amp;token_auth=<b>{$token_auth}</b></span><br />
     {'API_KeepTokenSecret'|translate:'<b>':'</b>'}
-    <p><i>{'API_LoadedAPIs'|translate:$countLoadedAPI}</i></p>
+    <!-- {'API_LoadedAPIs'|translate:$countLoadedAPI} -->
     {$list_api_methods_with_links}
     <br />
 </div>
diff --git a/plugins/Actions/API.php b/plugins/Actions/API.php
index bf8b61519d..9cceb05915 100644
--- a/plugins/Actions/API.php
+++ b/plugins/Actions/API.php
@@ -11,8 +11,17 @@
  */
 
 /**
- * Actions API
- *
+ * The Actions API lets you request reports for all your Visitor Actions: Page URLs, Page titles (Piwik Events),
+ * File Downloads and Clicks on external websites.
+ * 
+ * For example, "getPageTitles" will return all your page titles along with standard <a href='http://piwik.org/docs/analytics-api/reference/#toc-metric-definitions' target='_blank'>Actions metrics</a> for each row.
+ * 
+ * It is also possible to request data for a specific Page Title with "getPageTitle" 
+ * and setting the parameter pageName to the page title you wish to request. 
+ * Similarly, you can request metrics for a given Page URL via "getPageUrl", a Download file via "getDownload" 
+ * and an outlink via "getOutlink".
+ * 
+ * Note: pageName, pageUrl, outlinkUrl, downloadUrl parameters must be URL encoded before you call the API.
  * @package Piwik_Actions
  */
 class Piwik_Actions_API
@@ -32,6 +41,7 @@ class Piwik_Actions_API
 	/**
 	 * Backward compatibility. Fallsback to getPageTitles() instead.
 	 * @deprecated Deprecated since Piwik 0.5
+	 * @ignore
 	 */
 	public function getActions( $idSite, $period, $date, $segment = false, $expanded = false, $idSubtable = false )
 	{
diff --git a/plugins/CoreAdminHome/API.php b/plugins/CoreAdminHome/API.php
index efb82aacdd..48427bbf8b 100644
--- a/plugins/CoreAdminHome/API.php
+++ b/plugins/CoreAdminHome/API.php
@@ -11,7 +11,6 @@
  */
 
 /**
- *
  * @package Piwik_CoreAdminHome
  */
 class Piwik_CoreAdminHome_API 
diff --git a/plugins/CustomVariables/API.php b/plugins/CustomVariables/API.php
index 5bb639eae7..bb9b68b330 100644
--- a/plugins/CustomVariables/API.php
+++ b/plugins/CustomVariables/API.php
@@ -11,6 +11,7 @@
  */
 
 /**
+ * The Custom Variables API lets you access reports for your <a href='http://piwik.org/docs/custom-variables/' target='_blank'>Custom Variables</a> names and values.
  * 
  * @package Piwik_CustomVariables
  */
diff --git a/plugins/DBStats/API.php b/plugins/DBStats/API.php
index 9e07cfc223..bdce31c12a 100644
--- a/plugins/DBStats/API.php
+++ b/plugins/DBStats/API.php
@@ -11,7 +11,8 @@
  */
 
 /**
- *
+ * DBStats API is used to request the overall status of the Mysql tables in use by Piwik.
+ * 
  * @package Piwik_DBStats
  */
 class Piwik_DBStats_API
@@ -44,6 +45,7 @@ class Piwik_DBStats_API
 			$link   = mysql_connect($configDb['host'], $configDb['username'], $configDb['password']);
 			$status = mysql_stat($link);
 			mysql_close($link);
+			$status = explode("  ", $status);
 		}
 		else
 		{
@@ -55,14 +57,14 @@ class Piwik_DBStats_API
 			}
 
 			$status = array(
-				'Uptime: ' . $fullStatus['Uptime']['Value'],
-				'Threads: ' . $fullStatus['Threads_running']['Value'],
-				'Questions: ' . $fullStatus['Questions']['Value'],
-				'Slow queries: ' . $fullStatus['Slow_queries']['Value'],
-				'Opens: ', // not available via SHOW STATUS
-				'Flush tables: ' . $fullStatus['Flush_commands']['Value'],
-				'Open tables: ' . $fullStatus['Open_tables']['Value'],
-				'Queries per second avg: ', // not available via SHOW STATUS
+				'Uptime' => $fullStatus['Uptime']['Value'],
+				'Threads' => $fullStatus['Threads_running']['Value'],
+				'Questions' => $fullStatus['Questions']['Value'],
+				'Slow queries' => $fullStatus['Slow_queries']['Value'],
+				'Flush tables' => $fullStatus['Flush_commands']['Value'],
+				'Open tables' => $fullStatus['Open_tables']['Value'],
+//				'Opens: ', // not available via SHOW STATUS
+//				'Queries per second avg' =/ // not available via SHOW STATUS
 			);
 		}
 
diff --git a/plugins/ExampleAPI/API.php b/plugins/ExampleAPI/API.php
index b380f250b4..9310f749f3 100644
--- a/plugins/ExampleAPI/API.php
+++ b/plugins/ExampleAPI/API.php
@@ -11,30 +11,33 @@
  */
 
 /**
- * This is an example of a basic API file. Each plugin can have one public API.
- * Each public function in this class will be available to be called via the API.
- * Protected and private members will not be callable.
- * 
- * Functions can be called internally using the PHP objects directly, or via the 
- * Piwik Web APIs, using HTTP requests. For more information, check out:
- * http://piwik.org/docs/analytics-api/calling-techniques
- * 
- * Parameters are passed automatically from the GET request to the API functions.
- * 
- * Common API uses include: 
- * - requesting stats for a given date and period, for one or several websites
- * - creating, editing, deleting entities (Goals, Websites, Users)
- * - any logic that could be useful to a larger scope than the Controller (make a setting editable for example)
- * 
- * It is highly recommended that all the plugin logic is done inside API implementations, and the 
- * Controller and other objects would all call the API internally using, eg.
- *  Piwik_ExampleAPI_API::getInstance()->getSum(1, 2);
- * 
+ * The ExampleAPI is useful to developers building a custom Piwik plugin. 
  * 
+ * Please see the <a href='http://dev.piwik.org/trac/browser/trunk/plugins/ExampleAPI/API.php#L1' target='_blank'>source code in in the file plugins/ExampleAPI/API.php</a> for more documentation.
  * @package Piwik_ExampleAPI
  */
 class Piwik_ExampleAPI_API
 {
+	/**
+	 *  * This is an example of a basic API file. Each plugin can have one public API.
+	 * Each public function in this class will be available to be called via the API.
+	 * Protected and private members will not be callable.
+	 * Functions can be called internally using the PHP objects directly, or via the 
+	 * Piwik Web APIs, using HTTP requests. For more information, check out:
+	 * http://piwik.org/docs/analytics-api/calling-techniques
+	 * 
+	 * Parameters are passed automatically from the GET request to the API functions.
+	 * 
+	 * Common API uses include: 
+	 * - requesting stats for a given date and period, for one or several websites
+	 * - creating, editing, deleting entities (Goals, Websites, Users)
+	 * - any logic that could be useful to a larger scope than the Controller (make a setting editable for example)
+	 * 
+	 * It is highly recommended that all the plugin logic is done inside API implementations, and the 
+	 * Controller and other objects would all call the API internally using, eg.
+	 *  Piwik_ExampleAPI_API::getInstance()->getSum(1, 2);
+	 * 
+	 */
 	static private $instance = null;
 
 	/**
diff --git a/plugins/ExampleUI/API.php b/plugins/ExampleUI/API.php
index 02031a3dc8..07a1cb7202 100644
--- a/plugins/ExampleUI/API.php
+++ b/plugins/ExampleUI/API.php
@@ -11,6 +11,11 @@
  */
 
 /**
+ * ExampleUI API is also an example API useful if you are developing a Piwik plugin.
+ * 
+ * The functions listed in this API are returning the data used in the Controller to draw graphs and 
+ * display tables. See also the ExampleAPI plugin for an introduction to Piwik APIs.
+ * 
  * @package Piwik_ExampleUI
  */
 class Piwik_ExampleUI_API 
diff --git a/plugins/Goals/API.php b/plugins/Goals/API.php
index 34452468b9..8a9722e24a 100644
--- a/plugins/Goals/API.php
+++ b/plugins/Goals/API.php
@@ -11,7 +11,10 @@
  */
 
 /**
- *
+ * Goals API lets you Manage existing goals, via "updateGoal" and "deleteGoal", create new Goals via "addGoal", 
+ * or list existing Goals for one or several websites via "getGoals" 
+ * 
+ * It also lets you request overall Goal metrics via the method "get" and the additional helpers "getConversions", "getRevenue", etc.
  * @package Piwik_Goals
  */
 class Piwik_Goals_API 
diff --git a/plugins/LanguagesManager/API.php b/plugins/LanguagesManager/API.php
index fa73cc3149..97080d571e 100644
--- a/plugins/LanguagesManager/API.php
+++ b/plugins/LanguagesManager/API.php
@@ -12,7 +12,15 @@
  */
 
 /**
- *
+ * The LanguagesManager API lets you access existing Piwik translations, and change Users languages preferences.
+ * 
+ * "getTranslationsForLanguage" will return all translation strings for a given language, 
+ * so you can leverage Piwik translations in your application (and automatically benefit  from the 40+ translations!). 
+ * This is mostly useful to developers who integrate Piwik API results in their own application. 
+ * 
+ * You can also request the default language to load for a user via "getLanguageForUser", 
+ * or update it via "setLanguageForUser". 
+ * 
  * @package Piwik_LanguagesManager
  */
 class Piwik_LanguagesManager_API 
diff --git a/plugins/Live/API.php b/plugins/Live/API.php
index 4142c651e2..f4c8a0228c 100644
--- a/plugins/Live/API.php
+++ b/plugins/Live/API.php
@@ -16,6 +16,22 @@
 require_once PIWIK_INCLUDE_PATH . '/plugins/Live/Visitor.php';
 
 /**
+ * The Live! API lets you access complete visit level information about your visitors. Combined with the power of <a href='http://piwik.org/docs/analytics-api/segmentation/' target='_blank'>Segmentation</a>, 
+ * you will be able to requests visits filtered by any criteria. 
+ * 
+ * The method "getLastVisitsDetails" will return extensive data for each visit, which includes: server time, visitId, visitorId, 
+ * visitorType (new or returning), number of pages, list of all pages (and events, file downloaded and outlinks clicked), 
+ * custom variables names and values set to this visit, number of goal conversions (and list of all Goal conversions for this visit, 
+ * with time of conversion, revenue, URL, etc.), but also other attributes such as: days since last visit, days since first visit, 
+ * country, continent, visitor IP,
+ * provider, referrer used (referrer name, keyword if it was a search engine, full URL), campaign name and keyword, operating system, 
+ * browser, type of screen, resolution, supported browser plugins (flash, java, silverlight, pdf, etc.), various dates & times format to make
+ * it easier for API users... and more!
+ * 
+ * With the parameter <a href='http://piwik.org/docs/analytics-api/segmentation/' target='_blank'>'&segment='</a> you can filter the
+ * returned visits by any criteria (visitor IP, visitor ID, country, keyword used, time of day, etc.).
+ * 
+ * The method "getCounters" is used to return a simple counter: visits, number of actions, number of converted visits, in the last N minutes. 
  * @package Piwik_Live
  */
 class Piwik_Live_API
@@ -75,14 +91,10 @@ class Piwik_Live_API
 	}
 	
 	/**
-	 * Given a visitorId, will return the last $filter_limit visits for this visitor
+	 * The same functionnality can be obtained using segment=visitorId==$visitorId with getLastVisitsDetails
 	 * 
-	 * @param string 16 characters Visitor ID. Typically, you would use the Tracking JS getVisitorId() 
-	 * 					(or the PHP tracking equivalent getVisitorId()) to get this value
-	 * @param int Site ID
-	 * @param int Number of visits to return 
-	 * 
-	 * @return Piwik_DataTable
+	 * @deprecated
+	 * @ignore
 	 */
 	public function getLastVisitsForVisitor( $visitorId, $idSite, $filter_limit = 10 )
 	{
diff --git a/plugins/PDFReports/API.php b/plugins/PDFReports/API.php
index 828c73907d..6d828a46ba 100644
--- a/plugins/PDFReports/API.php
+++ b/plugins/PDFReports/API.php
@@ -11,7 +11,13 @@
  */
 
 /**
- *
+ * The PDFReports API lets you manage Scheduled Email reports, as well generate, download or email any existing report.
+ * 
+ * "generateReport" will generate the requested report (for a specific date range, website and in the requested language).
+ * "sendEmailReport" will send the report by email to the recipients specified for this report. 
+ * 
+ * You can also get the list of all existing reports via "getReports", create new reports via "addReport", 
+ * or manage existing reports with "updateReport" and "deleteReport".
  * @package Piwik_PDFReports
  */
 class Piwik_PDFReports_API
@@ -494,6 +500,9 @@ class Piwik_PDFReports_API
 		}
 	}
 
+	/**
+	 * @ignore
+	 */
 	static public function getPeriodToFrequency()
 	{
 		$periods = array(
diff --git a/plugins/Provider/API.php b/plugins/Provider/API.php
index ade1bcfaea..ce8752b369 100644
--- a/plugins/Provider/API.php
+++ b/plugins/Provider/API.php
@@ -16,6 +16,7 @@
 require_once PIWIK_INCLUDE_PATH . '/plugins/Provider/functions.php';
 
 /**
+ * The Provider API lets you access reports for your visitors Internet Providers.
  * 
  * @package Piwik_Provider
  */
diff --git a/plugins/Referers/API.php b/plugins/Referers/API.php
index 32e68548e5..b61d2b151a 100644
--- a/plugins/Referers/API.php
+++ b/plugins/Referers/API.php
@@ -11,7 +11,13 @@
  */
 
 /**
- *
+ * The Referrers API lets you access reports about Websites, Search engines, Keywords, Campaigns used to access your website.
+ * 
+ * For example, "getKeywords" returns all search engine keywords (with <a href='http://piwik.org/docs/analytics-api/reference/#toc-metric-definitions' target='_blank'>general analytics metrics</a> for each keyword), "getWebsites" returns referrer websites (along with the full Referrer URL if the parameter &expanded=1 is set). 
+ * "getRefererType" returns the Referrer overview report. "getCampaigns" returns the list of all campaigns (and all campaign keywords if the parameter &expanded=1 is set).
+ * 
+ * The methods "getKeywordsForPageUrl" and "getKeywordsForPageTitle" are used to output the top keywords used to find a page. 
+ * Check out the widget <a href='http://demo.piwik.org/index.php?module=Widgetize&action=iframe&moduleToWidgetize=Referers&actionToWidgetize=getKeywordsForPage&idSite=7&period=day&date=2011-02-15&disableLink=1' target='_blank'>"Top keywords used to find this page"</a> that you can easily re-use on your website.
  * @package Piwik_Referers
  */
 class Piwik_Referers_API 
diff --git a/plugins/SEO/API.php b/plugins/SEO/API.php
index fef074169a..502b545a9d 100644
--- a/plugins/SEO/API.php
+++ b/plugins/SEO/API.php
@@ -16,6 +16,9 @@
 require_once PIWIK_INCLUDE_PATH . '/plugins/Referers/functions.php';
 
 /**
+ * The SEO API lets you access a list of SEO metrics for the specified URL: Google Pagerank, Yahoo back links, Yahoo Indexed pages,
+ * Alexa Rank, and the age of the Domain name.
+ * 
  * @package Piwik_SEO
  */
 class Piwik_SEO_API 
diff --git a/plugins/SitesManager/API.php b/plugins/SitesManager/API.php
index 28646ff6eb..e7b84b8a9d 100644
--- a/plugins/SitesManager/API.php
+++ b/plugins/SitesManager/API.php
@@ -11,7 +11,19 @@
  */
 
 /**
- *
+ * The SitesManager API gives you full control on Websites in Piwik, with many methods to retrieve sites based on various attributes. 
+ * 
+ * This API lets you create websites via "addSite", update existing websites via "updateSite" and delete websites via "deleteSite".
+ * When creating websites, it can be useful to access internal codes used by Piwik for currencies via "getCurrencyList", or timezones via "getTimezonesList".
+ * 
+ * There are also many ways to request a list of websites: from the website ID via "getSiteFromId" or the site URL via "getSitesIdFromSiteUrl".
+ * Often, the most useful technique is to list all websites that are known to a current user, based on the token_auth, via
+ * "getSitesWithAdminAccess", "getSitesWithViewAccess" or "getSitesWithAtLeastViewAccess" (which returns both).
+ * 
+ * Some methods will affect all websites globally: "setGlobalExcludedIps" will set the list of IPs to be excluded on all websites,
+ * "setGlobalExcludedQueryParameters" will set the list of URL parameters to remove from URLs for all websites.
+ * The existing values can be fetched via "getExcludedIpsGlobal" and "getExcludedQueryParametersGlobal".
+ * 
  * @package Piwik_SitesManager
  */
 class Piwik_SitesManager_API 
diff --git a/plugins/UserCountry/API.php b/plugins/UserCountry/API.php
index c41fd8028b..296f6a2bb6 100644
--- a/plugins/UserCountry/API.php
+++ b/plugins/UserCountry/API.php
@@ -16,7 +16,7 @@
 require_once PIWIK_INCLUDE_PATH . '/plugins/UserCountry/functions.php';
 
 /**
- * 
+ * The UserCountry API lets you access reports about your visitors' Countries and Continents.
  * @package Piwik_UserCountry
  */
 class Piwik_UserCountry_API 
diff --git a/plugins/UserSettings/API.php b/plugins/UserSettings/API.php
index adcdbb6f73..32fbcddc67 100644
--- a/plugins/UserSettings/API.php
+++ b/plugins/UserSettings/API.php
@@ -16,7 +16,9 @@
 require_once PIWIK_INCLUDE_PATH . '/plugins/UserSettings/functions.php';
 
 /**
- *
+ * The UserSettings API lets you access reports about your Visitors technical settings: browsers, browser types (rendering engine), 
+ * operating systems, plugins supported in their browser, Screen resolution and Screen types (normal, widescreen, dual screen or mobile).
+ *  
  * @package Piwik_UserSettings
  */
 class Piwik_UserSettings_API 
diff --git a/plugins/UsersManager/API.php b/plugins/UsersManager/API.php
index 958b9452fd..f415611b2b 100644
--- a/plugins/UsersManager/API.php
+++ b/plugins/UsersManager/API.php
@@ -11,6 +11,15 @@
  */
 
 /**
+ * The UsersManager API lets you Manage Users and their permissions to access specific websites.
+ * 
+ * You can create users via "addUser", update existing users via "updateUser" and delete users via "deleteUser".
+ * There are many ways to list users based on their login "getUser" and "getUsers", their email "getUserByEmail", 
+ * or which users have permission (view or admin) to access the specified websites "getUsersWithSiteAccess".
+ * 
+ * Existing Permissions are listed given a login via "getSitesAccessFromUser", or a website ID via "getUsersAccessFromSite",   
+ * or you can list all users and websites for a given permission via "getUsersSitesFromAccess". Permissions are set and updated
+ * via the method "setUserAccess".
  * 
  * @package Piwik_UsersManager
  */
diff --git a/plugins/VisitFrequency/API.php b/plugins/VisitFrequency/API.php
index d00ca326f4..8cb246bd32 100644
--- a/plugins/VisitFrequency/API.php
+++ b/plugins/VisitFrequency/API.php
@@ -11,7 +11,7 @@
  */
 
 /**
- *
+ * VisitFrequency API lets you access a list of metrics related to Returning Visitors.
  * @package Piwik_VisitFrequency
  */
 class Piwik_VisitFrequency_API 
diff --git a/plugins/VisitTime/API.php b/plugins/VisitTime/API.php
index 843ea6687e..24d3658871 100644
--- a/plugins/VisitTime/API.php
+++ b/plugins/VisitTime/API.php
@@ -11,7 +11,8 @@
  */
 
 /**
- *
+ * VisitTime API lets you access reports by Hour (Server time), and by Hour Local Time of your visitors.
+ * 
  * @package Piwik_VisitTime
  */
 class Piwik_VisitTime_API
diff --git a/plugins/VisitorInterest/API.php b/plugins/VisitorInterest/API.php
index 87ddc924b6..512c766027 100644
--- a/plugins/VisitorInterest/API.php
+++ b/plugins/VisitorInterest/API.php
@@ -11,7 +11,9 @@
  */
 
 /**
- *
+ * VisitorInterest API lets you access two Visitor Engagement reports: number of visits per number of pages,
+ * and number of visits per visit duration.
+ * 
  * @package Piwik_VisitorInterest
  */
 class Piwik_VisitorInterest_API 
diff --git a/plugins/VisitsSummary/API.php b/plugins/VisitsSummary/API.php
index 15879a444f..7c252c900f 100644
--- a/plugins/VisitsSummary/API.php
+++ b/plugins/VisitsSummary/API.php
@@ -11,7 +11,9 @@
  */
 
 /**
- *
+ * VisitsSummary API lets you access the core web analytics metrics (visits, unique visitors, 
+ * count of actions (page views & downloads & clicks on outlinks), time on site, bounces and converted visits.
+ * 
  * @package Piwik_VisitsSummary
  */
 class Piwik_VisitsSummary_API