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

1 files changed, 22 insertions, 19 deletions

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;
 
 	/**