Refs #2450: Documented handler files.

git-svn-id: http://code.elgg.org/elgg/trunk@6942 36083f99-b078-4883-b0ff-0f9b5a30f544

5 files changed, 55 insertions, 41 deletions

diff --git a/engine/handlers/action_handler.php b/engine/handlers/action_handler.php
index f99e1efdc..8a1f1276b 100644
--- a/engine/handlers/action_handler.php
+++ b/engine/handlers/action_handler.php
@@ -1,17 +1,17 @@
 <?php
-
 /**
- * Elgg action handler
+ * Action handler.
+ *
+ * This file dispatches actions.  It is called via a URL rewrite in .htaccess
+ * from http://site/action/.  Anything after 'action/' is considered the action
+ * and will be passed to {@link action()}.
  *
- * @package Elgg
- * @subpackage Core
- * @author Curverider Ltd
- * @link http://elgg.org/
+ * @package Elgg.Core
+ * @subpackage Actions
+ * @link http://docs.elgg.org/Tutorials/Actions
  */
 
-/**
- *  Load Elgg framework
- */
 require_once("../start.php");
+
 $action = get_input("action");
 action($action);
\ No newline at end of file
diff --git a/engine/handlers/cron_handler.php b/engine/handlers/cron_handler.php
index a86cf7f4c..537b34f39 100644
--- a/engine/handlers/cron_handler.php
+++ b/engine/handlers/cron_handler.php
@@ -1,18 +1,21 @@
 <?php
 /**
- * Elgg Cron handler.
+ * Cron handlers
  *
- * @package Elgg
- * @subpackage Core
- * @author Curverider Ltd
- * @link http://elgg.org/
+ * This file dispatches cron actions.  It is called via a URL rewrite in .htaccess
+ * from http://site/p/.  Anything after 'action/' is considered the action
+ * and will be passed to {@link action()}.
+ *
+ * @package Elgg.Core
+ * @subpackage Actions
+ * @link http://docs.elgg.org/Tutorials/Actions
+ *
+ * @todo
  */
 
-// Load Elgg engine
 require_once("../start.php");
 global $CONFIG;
 
-// Get basic parameters
 $period = get_input('period');
 if (!$period) {
 	throw new CronException(sprintf(elgg_echo('CronException:unknownperiod'), $period));
@@ -26,8 +29,6 @@ foreach ($CONFIG->input as $k => $v) {
 	$params[$k] = $v;
 }
 
-// Trigger hack
-
 // Data to return to
 $std_out = "";
 $old_stdout = "";
diff --git a/engine/handlers/pagehandler.php b/engine/handlers/pagehandler.php
index 2e98c071a..a92c2f408 100644
--- a/engine/handlers/pagehandler.php
+++ b/engine/handlers/pagehandler.php
@@ -1,23 +1,27 @@
 <?php
 /**
- * Elgg page handler
+ * Pages handler.
  *
- * If page_handler() fails, send to front page.
+ * This file dispatches pages.  It is called via a URL rewrite in .htaccess
+ * from http://site/pg/handler/page1/page2.  The first element after 'pg/' is
+ * the page handler name as registered by {@link register_page_handler()}.
+ * The rest of the string is sent to {@link page_handler()}.
  *
- * @package Elgg
- * @subpackage Core
- * @author Curverider Ltd
- * @link http://elgg.org/
+ * {@link page_handler()} explodes the pages string by / and sends it to
+ * the page handler function as registered by {@link register_page_handler()}.
+ * If a valid page handler isn't found, the user will be forwarded to the site
+ * front page.
+ *
+ * @package Elgg.Core
+ * @subpackage PageHandler
+ * @link http://docs.elgg.org/Tutorials/PageHandlers
  */
 
-// Load Elgg engine
 require_once("../start.php");
 
-// Get input
 $handler = get_input('handler');
 $page = get_input('page');
 
-// Call the page handler functions
 if (!page_handler($handler, $page)) {
 	forward();
 }
\ No newline at end of file
diff --git a/engine/handlers/service_handler.php b/engine/handlers/service_handler.php
index 4cc54a987..c6a7e57c5 100644
--- a/engine/handlers/service_handler.php
+++ b/engine/handlers/service_handler.php
@@ -1,18 +1,26 @@
 <?php
 /**
- * Elgg web services handler.
+ * Services handler.
  *
- * @package Elgg
- * @subpackage Core
- * @author Curverider Ltd
- * @link http://elgg.org/
+ * This file dispatches requests to web services.  It is called via a URL rewrite
+ * in .htaccess from http://site/services/api/handler/response_format/request.
+ * The first element after 'services/api/' is the service handler name as
+ * registered by {@link register_service_handler()}.
+ *
+ * The remaining string is then passed to the {@link service_handler()}
+ * which explodes by /, extracts the first element as the response format
+ * (viewtype), and then passes the remaining array to the service handler
+ * function registered by {@link register_service_handler()}.
+ *
+ * If a service handler isn't found, a 404 header is sent.
+ *
+ * @package Elgg.Core
+ * @subpackage WebServices
+ * @link http://docs.elgg.org/Tutorials/WebServices
  */
 
-
-// Load Elgg engine
 require_once("../start.php");
 
-// Get input
 $handler = get_input('handler');
 $request = get_input('request');
 
diff --git a/engine/handlers/xml-rpc_handler.php b/engine/handlers/xml-rpc_handler.php
index 67d99a6ac..20f1c529c 100644
--- a/engine/handlers/xml-rpc_handler.php
+++ b/engine/handlers/xml-rpc_handler.php
@@ -1,14 +1,15 @@
 <?php
 /**
- * Elgg XML-RPC handler.
+ * XML-RPC handler.
  *
- * @package Elgg
- * @subpackage Core
- * @author Curverider Ltd
- * @link http://elgg.org/
+ * @warning This is very old code. Does it work at all?
+ *
+ * @package Elgg.Core
+ * @subpackage XMLRPC
+ * @link http://docs.elgg.org/Tutorials/XMLRPC
+ * @todo Does this work?
  */
 
-// Load Elgg engine
 require_once("../start.php");
 global $CONFIG;