Refs #2450: Added documentation to elgglib.

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

1 files changed, 540 insertions, 219 deletions

diff --git a/engine/lib/elgglib.php b/engine/lib/elgglib.php
index d4aa37a53..47d05327e 100644
--- a/engine/lib/elgglib.php
+++ b/engine/lib/elgglib.php
@@ -1,25 +1,22 @@
 <?php
 /**
- * Elgg library
- * Contains important functionality core to Elgg
+ * Bootstrapping and helper procedural code available for use in Elgg core and plugins.
  *
- * @package Elgg
- * @subpackage Core
- * @author Curverider Ltd
- * @link http://elgg.org/
- */
-
-/**
- * Getting directories and moving the browser
+ *
+ * @package Elgg.Core
+ * @todo These functions can't be subpackaged because they cover a wide mix of
+ * puposes and subsystems.  Many of them should be moved to more relevant files.
  */
 
 /**
- * Forwards the browser.
- * Returns false if headers have already been sent and the browser cannot be moved.
+ * Forward to $location.
+ *
+ * Sends a 'Location: $location' header and exists.  If headers have already been sent, returns FALSE.
  *
- * @param string $location URL to forward to browser to. Can be relative path.
- * @return nothing|false
- */function forward($location = "") {
+ * @param string $location URL to forward to browser to. Can be path relative to the network's URL.
+ * @return False False if headers have been sent. Terminates execution if forwarding.
+ */
+function forward($location = "") {
 	global $CONFIG;
 
 	if (!headers_sent()) {
@@ -27,14 +24,15 @@
 			$location = $_SERVER['HTTP_REFERER'];
 		}
 
-		$current_page = current_page_url();
 		if ((substr_count($location, 'http://') == 0) && (substr_count($location, 'https://') == 0)) {
 			$location = $CONFIG->url . $location;
 		}
 
 		// return new forward location or false to stop the forward or empty string to exit
+		$current_page = current_page_url();
 		$params = array('current_url' => $current_page, 'forward_url' => $location);
 		$location = trigger_plugin_hook('forward', 'system', $params, $location);
+
 		if ($location) {
 			header("Location: {$location}");
 			exit;
@@ -47,7 +45,13 @@
 }
 
 /**
- * Return the current page URL.
+ * Returns the current page's complete URL.
+ *
+ * The current URL is assembled using the network's wwwroot and the request URI
+ * in $_SERVER as populated by the web server.  This function will include
+ * any schemes, usernames and passwords, and ports.
+ *
+ * @return string The current page URL.
  */
 function current_page_url() {
 	global $CONFIG;
@@ -74,7 +78,6 @@ function current_page_url() {
 		$page .= ":" . $url['port'];
 	}
 
-	//$page.="/";
 	$page = trim($page, "/");
 
 	$page .= $_SERVER['REQUEST_URI'];
@@ -83,22 +86,33 @@ function current_page_url() {
 }
 
 /**
- * This is a factory function which produces an ElggCache object suitable for caching file load paths.
+ * Returns an ElggCache object suitable for caching view
+ * file load paths to disk under $CONFIG->dataroot.
  *
  * @todo Can this be done in a cleaner way?
  * @todo Swap to memcache etc?
+ *
+ * @return ElggFileCache A cache object suitable for caching file load paths.
  */
 function elgg_get_filepath_cache() {
 	global $CONFIG;
+
+	/**
+	 * A default filestore cache using the dataroot.
+	 */
 	static $FILE_PATH_CACHE;
-	if (!$FILE_PATH_CACHE) $FILE_PATH_CACHE = new ElggFileCache($CONFIG->dataroot);
+
+	if (!$FILE_PATH_CACHE) {
+		$FILE_PATH_CACHE = new ElggFileCache($CONFIG->dataroot);
+	}
 
 	return $FILE_PATH_CACHE;
 }
 
 /**
- * Function which resets the file path cache.
+ * Deletes the view file paths cache from disk.
  *
+ * @return bool On success
  */
 function elgg_filepath_cache_reset() {
 	$cache = elgg_get_filepath_cache();
@@ -106,9 +120,11 @@ function elgg_filepath_cache_reset() {
 }
 
 /**
- * Saves a filepath cache.
+ * Saves $data to the views file paths disk cache as
+ * 'view_paths'.
  *
- * @param mixed $data
+ * @param mixed $data The data
+ * @return bool On success
  */
 function elgg_filepath_cache_save($data) {
 	global $CONFIG;
@@ -122,8 +138,9 @@ function elgg_filepath_cache_save($data) {
 }
 
 /**
- * Retrieve the contents of the filepath cache.
+ * Returns the contents of the views file paths cache from disk.
  *
+ * @return mixed Null if simplecache isn't enabled, the contents of the views file paths cache if it is.
  */
 function elgg_filepath_cache_load() {
 	global $CONFIG;
@@ -141,25 +158,33 @@ function elgg_filepath_cache_load() {
 }
 
 /**
- * Enable the filepath cache.
+ * Enables the views file paths disk cache.
  *
+ * Uses the 'viewpath_cache_enabled' datalist with a boolean value.
+ * Resets the views paths cache.
+ *
+ * @return null
  */
 function elgg_enable_filepath_cache() {
 	global $CONFIG;
 
-	datalist_set('viewpath_cache_enabled',1);
+	datalist_set('viewpath_cache_enabled', 1);
 	$CONFIG->viewpath_cache_enabled = 1;
 	elgg_filepath_cache_reset();
 }
 
 /**
- * Disable filepath cache.
+ * Disables the views file paths disk cache.
+ *
+ * Uses the 'viewpath_cache_enabled' datalist with a boolean value.
+ * Resets the views paths cache.
  *
+ * @return null
  */
 function elgg_disable_filepath_cache() {
 	global $CONFIG;
 
-	datalist_set('viewpath_cache_enabled',0);
+	datalist_set('viewpath_cache_enabled', 0);
 	$CONFIG->viewpath_cache_enabled = 0;
 	elgg_filepath_cache_reset();
 }
@@ -203,7 +228,9 @@ function add_submenu_item($label, $link, $group = 'default', $onclick = false, $
 /**
  * Add an entry to the submenu.
  *
- * @param array $item The item as array(
+ * @param array $item The item as:
+ * <code>
+ * array(
  * 	'title' => 'Text to display',
  * 	'url' => 'URL of the link',
  * 	'id' => 'entry_unique_id' //used by children items to identify parents
@@ -211,11 +238,13 @@ function add_submenu_item($label, $link, $group = 'default', $onclick = false, $
  * 	'selected' => BOOL // Is this item selected? (If NULL or unset will attempt to guess)
  * 	'vars' => array() // Array of vars to pass to the navigation/submenu_item view
  * )
+ * </code>
  *
  * @param string $context Context in which to display this menu item.  'all' will make it show up all the time. Use sparingly.
  * @param string $group Group for the item. Each submenu group has its own <ul>
  * @return BOOL
  * @since 1.8
+ * @see elgg_prepare_submenu
  */
 function elgg_add_submenu_item(array $item, $context = 'all', $group = 'default') {
 	global $CONFIG;
@@ -267,6 +296,7 @@ function elgg_add_submenu_item(array $item, $context = 'all', $group = 'default'
  * @param string $context
  * @param bool $sort Sort the menu items alphabetically
  * @since 1.8
+ * @see elgg_add_submenu_item
  */
 function elgg_prepare_submenu($context = 'main', $sort = FALSE) {
 	global $CONFIG;
@@ -355,6 +385,7 @@ function elgg_prepare_submenu($context = 'main', $sort = FALSE) {
  * @param object $a
  * @param object $b
  * @since 1.8
+ * @see elgg_prepare_submenu
  */
 function elgg_submenu_item_cmp($a, $b) {
 	$a = $a->text;
@@ -381,6 +412,7 @@ function get_submenu() {
  * @param BOOL $sort Sort by display name?
  * @return string Formatted HTML.
  * @since 1.8
+ * @todo Rename to a view function. See {@trac #2320}.
  */
 function elgg_get_submenu($context = NULL, $sort = FALSE) {
 	global $CONFIG;
@@ -403,7 +435,6 @@ function elgg_get_submenu($context = NULL, $sort = FALSE) {
 		$temp_items = array();
 
 		while ($item = current($items)) {
-			$t = '';
 			// ignore parents created by a child but parent never defined properly
 			if (!isset($item->text) || !($item->text)) {
 				next($items);
@@ -460,20 +491,21 @@ function elgg_get_submenu($context = NULL, $sort = FALSE) {
 }
 
 /**
- * Automatically views likes and a like input relating to the given entity
+ * Returns the HTML for "likes" and "like this" on entities.
  *
  * @param ElggEntity $entity The entity to like
- * @return string|false The HTML (etc) for the likes, or false on failure
+ * @return string|false The HTML for the likes, or false on failure
  * @since 1.8
+ * @see @elgg_view likes/forms/edit
  */
 function elgg_view_likes($entity){
 	if (!($entity instanceof ElggEntity)) {
 		return false;
 	}
+
 	if ($likes = trigger_plugin_hook('likes', $entity->getType(), array('entity' => $entity), false)) {
 		return $likes;
 	} else {
-		//display the form
 		$likes = elgg_view('likes/forms/edit', array('entity' => $entity));
 		return $likes;
 	}
@@ -510,12 +542,6 @@ function elgg_count_comments($entity) {
 	}
 }
 
-
-
-/**
- * Library loading and handling
- */
-
 /**
  * @deprecated 1.7
  */
@@ -525,13 +551,15 @@ function get_library_files($directory, $exceptions = array(), $list = array()) {
 }
 
 /**
- * Returns a list of files in $directory
+ * Returns a list of files in $directory.
  *
- * @param str $directory
+ * Only returns files.  Does not recurse into subdirs.
+ *
+ * @param string $directory
  * @param array $exceptions Array of filenames to ignore
  * @param array $list Array of files to append to
- * @param mixed $extensions Array of extensions to allow, NULL for all. (With a dot: array('.php'))
- * @return array of filenames including $directory
+ * @param mixed $extensions Array of extensions to allow, NULL for all.  Use a dot: array('.php').
+ * @return array Filenames in $directory, in the form $directory/filename.
  */
 function elgg_get_file_list($directory, $exceptions = array(), $list = array(), $extensions = NULL) {
 	$directory = sanitise_filepath($directory);
@@ -556,10 +584,25 @@ function elgg_get_file_list($directory, $exceptions = array(), $list = array(),
 }
 
 /**
- * Ensures that the installation has all the correct files, that PHP is configured correctly, and so on.
- * Leaves appropriate messages in the error register if not.
+ * Checks that Elgg has been installed and attempts to complete installation if not.
+ *
+ * This is called by {@link engine/start.php} immediately after Elgg libraries are loaded
+ * to check the installation state.
+ *
+ * Elgg's installation state is determined by (1) the existence of the engine/settings.php
+ * file, (2) a .htaccess file, and (3) a populated database.  This function checks
+ * for 1 and 2, while 3 is checked by {@link is_installed()} and {@link is_db_installed()}.
+ *
+ * If settings.php doesn't exist and $_REQUEST['db_install_vars'] is present,
+ * this function attempts to write the values from 'db_install_vars' to settings.php.
+ *
+ * If .htaccess doens't exist this function attempts to copy htaccess_dist to .htaccess.
+ *
+ * If there are any problems, this function calls {@link register_error()} and returns FALSE.
+ * Since this function is called during bootstrapping, the viewtype is failsafe.
+ * Returning FALSE results in an InstallationException, which halts execution.
  *
- * @return true|false True if everything is ok (or Elgg is fit enough to run); false if not.
+ * @return bool
  */
 function sanitised() {
 	$sanitised = true;
@@ -608,18 +651,16 @@ function sanitised() {
 }
 
 /**
- * Registers
- */
-
-/**
- * Adds an array with a name to a given generic array register.
- * For example, these are used for menus.
+ * Adds an entry in $CONFIG[$register_name][$subregister_name].
+ *
+ * This is only used for the site-wide menu.  See {@link add_menu()}.
  *
  * @param string $register_name The name of the top-level register
  * @param string $subregister_name The name of the subregister
  * @param mixed $subregister_value The value of the subregister
  * @param array $children_array Optionally, an array of children
  * @return true|false Depending on success
+ * @todo Can be deprecated when the new menu system is introduced.
  */
 function add_to_register($register_name, $subregister_name, $subregister_value, $children_array = array()) {
 	global $CONFIG;
@@ -649,12 +690,15 @@ function add_to_register($register_name, $subregister_name, $subregister_value,
 }
 
 /**
- * Removes what has been registered at [register_name][subregister_name]
+ * Removes a register entry from $CONFIG[register_name][subregister_name]
+ *
+ * This is used to by {@link remove_menu()} to remove site-wide menu items.
  *
  * @param string $register_name The name of the top-level register
  * @param string $subregister_name The name of the subregister
  * @return true|false Depending on success
  * @since 1.7.0
+ * @todo Can be deprecated when the new menu system is introduced.
  */
 function remove_from_register($register_name, $subregister_name) {
 	global $CONFIG;
@@ -680,12 +724,13 @@ function remove_from_register($register_name, $subregister_name) {
 }
 
 /**
- * Returns a register object
+ * Constructs and returns a register object.
  *
  * @param string $register_name The name of the register
  * @param mixed $register_value The value of the register
  * @param array $children_array Optionally, an array of children
  * @return false|stdClass Depending on success
+ * @todo Can be deprecated when the new menu system is introduced.
  */
 function make_register_object($register_name, $register_value, $children_array = array()) {
 	elgg_deprecated_notice('make_register_object() is deprecated by add_submenu_item()', 1.7);
@@ -706,6 +751,7 @@ function make_register_object($register_name, $register_value, $children_array =
  *
  * @param string $register_name The name of the register
  * @return array|false Depending on success
+ * @todo Can be deprecated when the new menu system is introduced.
  */
 function get_register($register_name) {
 	global $CONFIG;
@@ -718,15 +764,16 @@ function get_register($register_name) {
 }
 
 /**
- * Adds an item to the menu register
- * This is used in the core to create the tools dropdown menu
- * You can obtain the menu array by calling get_register('menu')
+ * Adds an item to the site-wide menu.
+ *
+ * You can obtain the menu array by calling {@link get_register('menu')}
  *
  * @param string $menu_name The name of the menu item
  * @param string $menu_url The URL of the page
  * @param array $menu_children Optionally, an array of submenu items (not currently used)
  * @param string $context
  * @return true|false Depending on success
+ * @todo Can be deprecated when the new menu system is introduced.
  */
 function add_menu($menu_name, $menu_url, $menu_children = array(), $context = "") {
 	global $CONFIG;
@@ -759,11 +806,12 @@ function remove_menu($menu_name) {
 
 /**
  * Returns a menu item for use in the children section of add_menu()
- * This is not currently used in the Elgg core
+ * This is not currently used in the Elgg core.
  *
  * @param string $menu_name The name of the menu item
  * @param string $menu_url Its URL
  * @return stdClass|false Depending on success
+ * @todo Can be deprecated when the new menu system is introduced.
  */
 function menu_item($menu_name, $menu_url) {
 	elgg_deprecated_notice('menu_item() is deprecated by add_submenu_item', 1.7);
@@ -771,14 +819,30 @@ function menu_item($menu_name, $menu_url) {
 }
 
 /**
- * Message register handling
- * If a null $message parameter is given, the function returns the array of messages so far and empties it
- * based on the $register parameters. Otherwise, any message or array of messages is added.
+ * Queues a message to be displayed.
+ *
+ * Messages will not be displayed immediately, but are stored in
+ * for later display, usually upon next page load.
+ *
+ * The method of displaying these messages differs depending upon plugins and
+ * viewtypes.  The core default viewtype retrieves messages in {@link views/default/page_shells/default.php}
+ * and displays messages as javascript popups.
+ *
+ * @internal Messages are stored as strings in the $_SESSION['msg'][$register] array.
+ *
+ * @warning This function is used to both add to and clear the message
+ * stack.  If $messages is null, $register will be returned and cleared.
+ * If $messages is null and $register is empty, all messages will be
+ * returned and removed.
+ *
+ * @important This function handles the standard {@link system_message()} ($register =
+ * 'messages') as well as {@link register_error()} messages ($register = 'errors').
  *
  * @param string|array $message Optionally, a single message or array of messages to add, (default: null)
  * @param string $register This allows for different types of messages: "errors", "messages" (default: messages)
  * @param bool $count Count the number of messages (default: false)
  * @return true|false|array Either the array of messages, or a response regarding whether the message addition was successful
+ * @todo Clean up. Separate registering messages and retrieving them.
  */
 function system_messages($message = null, $register = "messages", $count = false) {
 	if (!isset($_SESSION['msg'])) {
@@ -826,22 +890,24 @@ function system_messages($message = null, $register = "messages", $count = false
  * @return integer The number of messages
  */
 function count_messages($register = "") {
-	return system_messages(null,$register,true);
+	return system_messages(null, $register, true);
 }
 
 /**
- * An alias for system_messages($message) to handle standard user information messages
+ * Display a system message on next page load.
  *
+ * @see system_messages()
  * @param string|array $message Message or messages to add
- * @return true|false Success response
+ * @return Bool
  */
 function system_message($message) {
 	return system_messages($message, "messages");
 }
 
 /**
- * An alias for system_messages($message) to handle error messages
+ * Display an error on next page load.
  *
+ * @see system_messages()
  * @param string|array $message Error or errors to add
  * @return true|false Success response
  */
@@ -850,26 +916,25 @@ function register_error($error) {
 }
 
 /**
- * Event register
- * Adds functions to the register for a particular event, but also calls all functions registered to an event when required
- *
- * Event handler functions must be of the form:
- *
- * 		event_handler_function($event, $object_type, $object);
- *
- * And must return true or false depending on success.  A false will halt the event in its tracks and no more functions will be called.
+ * Register a callback function as a handler or trigger registered handlers for an event.
  *
- * You can then simply register them using the following function. Optionally, this can be called with a priority nominally from 0 to 1000, where functions with lower priority values are called first (note that priorities CANNOT be negative):
+ * Elgg emits an event when certain core actions occur, like creating an entity.
+ * Functions registered to these events can respond to the event, prevent the
+ * event from completing, or ignore the event.
  *
- * 		register_elgg_event_handler($event, $object_type, $function_name [, $priority = 500]);
+ * Callback functions are registered with {@link register_elgg_event_handler()}
  *
- * Note that you can also use 'all' in place of both the event and object type.
+ * When an event is triggered ({@link trigger_elgg_event()}, each callback function is
+ * run in order of priority.  Any callback that returns false will halt execution
+ * and control will be passed back to the caller.
  *
- * To trigger an event properly, you should always use:
+ * @internal Events are stored in $CONFIG->events as:
+ * <code>
+ * $CONFIG->events[$event][$type][$priority] = 'callback_function'
+ * </code>
  *
- * 		trigger_elgg_event($event, $object_type [, $object]);
- *
- * Where $object is optional, and represents the $object_type the event concerns. This will return true if successful, or false if it fails.
+ * @note You cannot generally alter the event, only halt it.
+ * @tip Plugin authors should use {@link register_elgg_event_handler()} to register events.
  *
  * @param string $event The type of event (eg 'init', 'update', 'delete')
  * @param string $object_type The type of object (eg 'system', 'blog', 'user')
@@ -878,6 +943,12 @@ function register_error($error) {
  * @param boolean $call Set to true to call the event rather than add to it (default false)
  * @param mixed $object Optionally, the object the event is being performed on (eg a user)
  * @return true|false Depending on success
+ *
+ * @todo Separate registering and calling events. {@trac #2466}
+ * @example events/basic.php Register and respond to an Elgg event
+ * @example events/advanced.php Register for an Elgg event and optionally halt it.
+ * @internal @example events/emit.php Basic emitting of an Elgg event.
+ * @link http://docs.elgg.org/Tutorials/Core/Events
  */
 function events($event = "", $object_type = "", $function = "", $priority = 500, $call = false, $object = null) {
 	global $CONFIG;
@@ -947,19 +1018,63 @@ function events($event = "", $object_type = "", $function = "", $priority = 500,
 }
 
 /**
- * Alias function for events, that registers a function to a particular kind of event
+ * Register a callback function as an Elgg event handler.
+ *
+ * Events are emitted by Elgg when certain actions occur.  Plugins
+ * can respond to these events or halt them completely by registering a handler
+ * as a callback function to an event.  Multiple handlers can be registered for
+ * the same event and will be executed in order of $priority.  Any handler
+ * returning false will halt the execution chain.
+ *
+ * This function is called with the event name, event type, and handler function name.
+ * Setting the optional $priority allows plugin authors to specify when the
+ * function should be run.  Priorities for plugins should be 1-1000.
+ *
+ * The callback function is passed 3 arguments when called: $event, $type, and optional $params.
+ *
+ * $event is the name of event being emitted.
+ * $type is the type of event or object concerned.
+ * $params is an optional parameter passed that can include a related object.  See
+ * specific event documentation for details on which events pass what parameteres.
+ *
+ * @tip If a priority isn't specified it is determined by the order the handler was
+ * registered relative to the event and type.  For plugins, this generally means
+ * the earlier the plugin is in the load order, the earlier the priorities are for
+ * any event handlers.
+ *
+ * @tip $event and $object_type can use the special keyword 'all'.  Handler functions registered
+ * with $event = all will be called for all events of type $object_type.  Similarly,
+ * functions registered with $object_type = all will be called for all events of type
+ * $event, regardless of $object_type.  If $event and $object_type both are 'all', the
+ * handler function will be called for all events.
+ *
+ * @tip Event handler functions are considered in the follow order:
+ *  - Specific registration where 'all' isn't used.
+ *  - Registration where 'all' is used for $event only.
+ *  - Registration where 'all' is used for $type only.
+ *  - Registration where 'all' is used for both.
+ *
+ * @warning If you use the 'all' keyword, you must have logic in the handler function to
+ * test the passed parameters before taking an action.
+ *
+ * @tip When referring to events, the preferred syntax is "event:type".
  *
  * @param string $event The event type
  * @param string $object_type The object type
- * @param string $function The function name
- * @return true|false Depending on success
+ * @param string $function The handler callback function name
+ * @param int $priority The priority of the event
+ * @return bool
+ * @link http://docs.elgg.org/Tutorials/Plugins/Events
+ * @example events/basic.php Basic example of registering an event handler callback function.
+ * @example events/advanced.php Advanced example of registering an event handler callback function and halting execution.
+ * @example events/all.php Example of how to use the 'all' keyword.
  */
 function register_elgg_event_handler($event, $object_type, $function, $priority = 500) {
 	return events($event, $object_type, $function, $priority);
 }
 
 /**
- * Unregisters a function to a particular kind of event
+ * Unregisters a callback function from an event.
  *
  * @param string $event The event type
  * @param string $object_type The object type
@@ -976,12 +1091,33 @@ function unregister_elgg_event_handler($event, $object_type, $function) {
 }
 
 /**
- * Alias function for events, that triggers a particular kind of event
+ * Trigger an Elgg Event and run all handler functions registered to that event:type.
+ *
+ * This function runs all handlers regsitered to $event:$object_type or
+ * the special keyword 'all' for either or both.
+ *
+ * $event is usually a verb: create, update, delete, annotation.
+ *
+ * $object_type is usually a noun: object, group, user, annotation, relationship, metadata.
+ *
+ * $object is usually an Elgg* object assciated with the event.
+ *
+ * @warning Elgg events should only be called by core.  Plugin authors should use
+ * {@link trigger_elgg_plugin_hook()} instead.
+ *
+ * @tip When referring to events, the preferred syntax is "event:type".
+ *
+ * @internal Only rarely should events be changed, added, or removed in core.
+ * When making changes to events, be sure to first create a ticket in trac.
+ *
+ * @internal @tip Think of $object_type as the primary namespace element, and
+ * $event as the secondary namespace.
  *
  * @param string $event The event type
  * @param string $object_type The object type
  * @param string $function The function name
- * @return true|false Depending on success
+ * @return bool The result of running all handler functions.
+ * @link http://docs.elgg.org/Tutorials/Core/Events
  */
 function trigger_elgg_event($event, $object_type, $object = null) {
 	$return = true;
@@ -993,27 +1129,68 @@ function trigger_elgg_event($event, $object_type, $object = null) {
 }
 
 /**
- * Register a function to a plugin hook for a particular hook name and type, with a given priority.
+ * Register a callback function as a plugin hook handler.
  *
- * eg if you want the function "export_user" to be called when the hook "export" for "user" entities
- * is run, use:
+ * Plugin hooks allow developers to losely couple plugins and features by
+ * repsonding to and emitting {@link trigger_plugin_hook()} customizable hooks.
+ * Handler functions can respond to the hook, change the details of the hook, or ignore it.
  *
- * 		register_plugin_hook("export", "user", "export_user");
+ * Multiple handlers can be registered for a plugin hook, and each callback
+ * function is called in order of priority.  If the return value of a handler
+ * function is not null, that value is passed to the next function in the
+ * call stack.  When all functions have been run, the final value is passed
+ * back to the caller via {@link trigger_plugin_hook()}.
  *
- * "all" is a valid value for both $hook and $entity_type. "none" is a valid value for $entity_type.
+ * Similar to Elgg Events, plugin hook handler functions are registered by passing
+ * a hook, a type, and a priority.
  *
- * The export_user function would then be defined as:
+ * The callback function is passed 4 arguments when called: $hook, $type
+ * $value, and $params.
  *
- * 		function export_user($hook, $entity_type, $returnvalue, $params);
+ *  - str $hook The name of the hook.
+ *  - str $type The type of hook.
+ *  - mixed $value The return value of the last handler or the default
+ *  value if no other handlers have been called.
+ *  - mixed $params An optional array of parameters.  Used to provide additional information
+ *  to plugins.
  *
- * Where $returnvalue is the return value returned by the last function returned by the hook, and
- * $params is an array containing a set of parameters (or nothing).
+ * @internal Plugin hooks are stored in $CONFIG->hooks as:
+ * <code>
+ * $CONFIG->hooks[$hook][$type][$priority] = 'callback_function'
+ * </code>
+ *
+ * @tip Plugin hooks are similar to Elgg Events in that Elgg emits
+ * a plugin hook when certain actions occur, but a plugin hook allows you to alter the
+ * parameters, as well as halt execution.
+ *
+ * @tip If a priority isn't specified it is determined by the order the handler was
+ * registered relative to the event and type.  For plugins, this generally means
+ * the earlier the plugin is in the load order, the earlier the priorities are for
+ * any event handlers.
+ *
+ * @tip Like Elgg Events, $hook and $type can use the special keyword 'all'.
+ * Handler functions registered with $hook = all will be called for all hooks
+ * of type $type.  Similarly, handlers registered with $type = all will be
+ * called for all hooks of type $event, regardless of $object_type.  If $hook
+ * and $type both are 'all', the handler will be called for all hooks.
+ *
+ * @tip Plugin hooks are sometimes used to gather lists from plugins.  This is
+ * usually done by pushing elements into an array passed in $params.  Be sure
+ * to append to and then return $value so you don't overwrite other plugin's
+ * values.
+ *
+ * @warning Unlike Elgg Events, a handler that returns false will NOT halt the
+ * execution chain.
  *
  * @param string $hook The name of the hook
- * @param string $type The type of the hook (NB Can be an ElggEntity type [user, object, group, site] or custom-defined 'get_sections')
+ * @param string $type The type of the hook
  * @param string $function The name of a valid function to be run
  * @param string $priority The priority - 0 is first, 1000 last, default is 500
- * @return true|false Depending on success
+ * @return bool
+ *
+ * @example hooks/register/basic.php Registering for a plugin hook and examining the variables.
+ * @example hooks/register/advanced.php Registering for a plugin hook and changing the params.
+ * @link http://docs.elgg.org/Tutorials/Plugins/Hooks
  */
 function register_plugin_hook($hook, $type, $function, $priority = 500) {
 	global $CONFIG;
@@ -1043,7 +1220,7 @@ function register_plugin_hook($hook, $type, $function, $priority = 500) {
 }
 
 /**
- * Unregister a function to a plugin hook for a particular entity type
+ * Unregister a callback function as a plugin hook.
  *
  * @param string $hook The name of the hook
  * @param string $entity_type The name of the type of entity (eg "user", "object" etc)
@@ -1060,18 +1237,38 @@ function unregister_plugin_hook($hook, $entity_type, $function) {
 }
 
 /**
- * Triggers a plugin hook, with various parameters as an array. For example, to provide
- * a 'foo' hook that concerns the type 'bar', with a parameter called 'param1'
- * with value 'value1', that by default returns true, you'd call:
+ * Trigger a Plugin Hook and run all handler functions registered to that hook:type.
+ *
+ * This function runs all handlers regsitered to $hook:$type or
+ * the special keyword 'all' for either or both.
+ *
+ * Use $params to send additional information to the handler functions.
+ *
+ * $returnvalue Is the initial value to pass to the handlers, which can
+ * then change it.  It is useful to use $returnvalue to set defaults.
+ * If no handlers are registered, $returnvalue is immediately returned.
  *
- * trigger_plugin_hook('foo', 'bar', array('param1' => 'value1'), true);
+ * $hook is usually a verb: import, get_views, output.
  *
- * @see register_plugin_hook
+ * $type is usually a noun: user, ecml, page.
+ *
+ * @tip Like Elgg Events, $hook and $type can use the special keyword 'all'.
+ * Handler functions registered with $hook = all will be called for all hooks
+ * of type $type.  Similarly, handlers registered with $type = all will be
+ * called for all hooks of type $event, regardless of $object_type.  If $hook
+ * and $type both are 'all', the handler will be called for all hooks.
+ *
+ * @see register_plugin_hook()
  * @param string $hook The name of the hook to trigger (NB: "all" will trigger for all $types regardless of $hook value)
  * @param string $type The type of the hook to trigger (NB: "all" will trigger for all $hooks regardless of $type value)
- * @param array $params Any parameters. It's good practice to name the keys, i.e. by using array('name' => 'value', 'name2' => 'value2')
+ * @param mixed $params Additional parameters to pass to the handlers
  * @param mixed $returnvalue An initial return value
- * @return mixed|null The cumulative return value for the plugin hook functions
+ * @return mixed|null The return value of the last handler function called
+ *
+ * @example hooks/trigger/basic.php Trigger a hook that determins if execution should continue.
+ * @example hooks/trigger/advanced.php Trigger a hook with a default value and use the results to populate a menu.
+ * @example hooks/basic.php Trigger and respond to a basic plugin hook.
+ * @link http://docs.elgg.org/Tutorials/Plugins/Hooks
  */
 function trigger_plugin_hook($hook, $type, $params = null, $returnvalue = null) {
 	global $CONFIG;
@@ -1088,7 +1285,9 @@ function trigger_plugin_hook($hook, $type, $params = null, $returnvalue = null)
 	if (!empty($CONFIG->hooks['all'][$type]) && is_array($CONFIG->hooks['all'][$type])) {
 		foreach($CONFIG->hooks['all'][$type] as $hookfunction) {
 			$temp_return_value = $hookfunction($hook, $type, $returnvalue, $params);
-			if (!is_null($temp_return_value)) $returnvalue = $temp_return_value;
+			if (!is_null($temp_return_value)) {
+				$returnvalue = $temp_return_value;
+			}
 		}
 	}
 
@@ -1114,12 +1313,15 @@ function trigger_plugin_hook($hook, $type, $params = null, $returnvalue = null)
 }
 
 /**
- * Error handling
- */
-
-/**
- * PHP Error handler function.
- * This function acts as a wrapper to catch and report PHP error messages.
+ * Intercepts catchable PHP errors.
+ *
+ * @warning This function should never be called directly.
+ *
+ * @internal
+ * For catchable fatal errors, throws an Exception with the error.
+ *
+ * For non-fatal errors, depending upon the debug settings, either
+ * log the error or ignore it.
  *
  * @see http://www.php.net/set-error-handler
  * @param int $errno The level of the error raised
@@ -1156,18 +1358,21 @@ function __elgg_php_error_handler($errno, $errmsg, $filename, $linenum, $vars) {
 }
 
 /**
- * Throws a message to the Elgg logger
+ * Display or log a message.
+ *
+ * If $level is >= to the debug setting in {@link $CONFIG->debug}, the
+ * message will be sent to {@link elgg_dump()}.  Messages with lower
+ * priority than {@link $CONFIG->debug} are ignored.
  *
- * The Elgg log is currently implemented such that any messages sent at a level
- * greater than or equal to the debug setting will be sent to elgg_dump.
- * The default location for elgg_dump is the screen except for notices.
+ * {@link elgg_dump()} outputs all levels but NOTICE to screen by default.
  *
- * Note: No messages will be displayed unless debugging has been enabled.
+ * @note No messages will be displayed unless debugging has been enabled.
  *
  * @param str $message User message
  * @param str $level NOTICE | WARNING | ERROR | DEBUG
  * @return bool
  * @since 1.7.0
+ * @todo This is complicated and confusing.  Using int constants for debug levels will make things easier.
  */
 function elgg_log($message, $level='NOTICE') {
 	global $CONFIG;
@@ -1205,11 +1410,13 @@ function elgg_log($message, $level='NOTICE') {
 }
 
 /**
- * Extremely generic var_dump-esque wrapper
+ * Logs or displays $value.
+ *
+ * If $to_screen is true, $value is displayed to screen.  Else,
+ * it is handled by PHP's {@link error_log()} function.
  *
- * Immediately dumps the given $value as a human-readable string.
- * The $value can instead be written to the screen or server log depending on
- * the value of the $to_screen flag.
+ * A {@elgg_plugin_hook debug:log} is called.  If a handler returns
+ * false, it will stop the default logging method.
  *
  * @param mixed $value
  * @param bool $to_screen
@@ -1245,8 +1452,9 @@ function elgg_dump($value, $to_screen = TRUE, $level = 'NOTICE') {
 }
 
 /**
- * Custom exception handler.
- * This function catches any thrown exceptions and handles them appropriately.
+ * Intercepts, logs, and display uncaught exceptions.
+ *
+ * @warning This function should never be called directly.
  *
  * @see http://www.php.net/set-exception-handler
  * @param Exception $exception The exception being handled
@@ -1254,33 +1462,43 @@ function elgg_dump($value, $to_screen = TRUE, $level = 'NOTICE') {
 function __elgg_php_exception_handler($exception) {
 	error_log("*** FATAL EXCEPTION *** : " . $exception);
 
-	ob_end_clean(); // Wipe any existing output buffer
+	// Wipe any existing output buffer
+	ob_end_clean();
 
 	// make sure the error isn't cached
 	header("Cache-Control: no-cache, must-revalidate", true);
 	header('Expires: Fri, 05 Feb 1982 00:00:00 -0500', true);
+	// @todo Why don't we send a 500 header?
 	//header("Internal Server Error", true, 500);
 
-	$body = elgg_view("messages/exceptions/exception",array('object' => $exception));
+	$body = elgg_view("messages/exceptions/exception", array('object' => $exception));
 	page_draw(elgg_echo('exception:title'), $body);
 }
 
 /**
- * Data lists
+ * An array of key value pairs from the datalists table.
+ *
+ * Used as a cache in datalist functions.
+ *
+ * @global array $DATALIST_CACHE
  */
-
 $DATALIST_CACHE = array();
 
 /**
- * Get the value of a particular piece of data in the datalist
+ * Get the value of a datalist element.
  *
- * @param string $name The name of the datalist
- * @return string|false Depending on success
+ * @internal Datalists are stored in the datalist table.
+ *
+ * @tip Use datalists to store information common to a full installation.
+ *
+ * @param string $name The name of the datalist element
+ * @return string|false The datalist value or false if it doesn't exist.
  */
 function datalist_get($name) {
 	global $CONFIG, $DATALIST_CACHE;
 
-	// We need this, because sometimes datalists are received before the database is created
+	// We need this, because sometimes datalists are attempted
+	// to be retrieved before the database is created
 	if (!is_db_installed()) {
 		return false;
 	}
@@ -1320,28 +1538,17 @@ function datalist_get($name) {
 		}
 	}
 
-
-	/*if ($row = get_data_row("SELECT value from {$CONFIG->dbprefix}datalists where name = '{$name}' limit 1")) {
-		$DATALIST_CACHE[$name] = $row->value;
-
-		// Cache it if memcache is available
-		if ($datalist_memcache) $datalist_memcache->save($name, $row->value);
-
-		return $row->value;
-	}*/
-
 	return false;
 }
 
 /**
- * Sets the value for a system-wide piece of data (overwriting a previous value if it exists)
+ * Set the value for a datalist element.
  *
  * @param string $name The name of the datalist
  * @param string $value The new value
  * @return true
  */
 function datalist_set($name, $value) {
-
 	global $CONFIG, $DATALIST_CACHE;
 
 	$name = sanitise_string($name);
@@ -1357,7 +1564,6 @@ function datalist_set($name, $value) {
 		$datalist_memcache->delete($name);
 	}
 
-	//delete_data("delete from {$CONFIG->dbprefix}datalists where name = '{$name}'");
 	insert_data("INSERT into {$CONFIG->dbprefix}datalists set name = '{$name}', value = '{$value}' ON DUPLICATE KEY UPDATE value='{$value}'");
 
 	$DATALIST_CACHE[$name] = $value;
@@ -1366,14 +1572,25 @@ function datalist_set($name, $value) {
 }
 
 /**
- * Runs a function once - not per page load, but per installation.
- * If you like, you can also set the threshold for the function execution - i.e.,
- * if the function was executed before or on $timelastupdatedcheck, this
- * function will run it again.
+ * Run a function one time per installation.
+ *
+ * If you pass a timestamp as the second argument, it will run the function
+ * only if (i) it has never been run before or (ii) the timestamp is >=
+ * the last time it was run.
+ *
+ * @warning Functions are determined by their name.  If you change the name of a function
+ * it will be run again.
+ *
+ * @tip Use $timelastupdatedcheck in your plugins init function to perform automated
+ * upgrades.  Schedule a function to run once and pass the timestamp of the new release.
+ * This will cause the run once function to be run on all installations.  To perform
+ * additional upgrades, create new functions for each release.
+ *
+ * @internal A datalist entry $functioname is created with the value of time().
  *
  * @param string $functionname The name of the function you want to run.
- * @param int $timelastupdatedcheck Optionally, the UNIX epoch timestamp of the execution threshold
- * @return true|false Depending on success.
+ * @param int $timelastupdatedcheck A UNIX timestamp. If time() is > than this, this function will be run again.
+ * @return bool
  */
 function run_function_once($functionname, $timelastupdatedcheck = 0) {
 	if ($lastupdated = datalist_get($functionname)) {
@@ -1383,7 +1600,7 @@ function run_function_once($functionname, $timelastupdatedcheck = 0) {
 	}
 	if (is_callable($functionname) && $lastupdated <= $timelastupdatedcheck) {
 		$functionname();
-		datalist_set($functionname,time());
+		datalist_set($functionname, time());
 		return true;
 	} else {
 		return false;
@@ -1392,12 +1609,21 @@ function run_function_once($functionname, $timelastupdatedcheck = 0) {
 
 /**
  * Sends a notice about deprecated use of a function, view, etc.
- * Note: This will ALWAYS at least log a warning.  Don't use to pre-deprecate things.
+ *
+ * This function either displays or logs the deprecation message,
+ * depending upon the deprecation policies in {@link CODING.txt}.
+ * Logged messages are sent with the level of 'WARNING'.
+ *
+ * A user-visual message will be displayed if $dep_version is greater
+ * than 1 minor releases lower than the current Elgg version, or at all
+ * lower than the current Elgg major version.
+ *
+ * @note This will always at least log a warning.  Don't use to pre-deprecate things.
  * This assumes we are releasing in order and deprecating according to policy.
  *
+ * @see CODING.txt
  * @param str $msg Message to log / display.
- * @param str $version human-readable *release* version the function was deprecated. No bloody A, B, (R)C, or D.
- *
+ * @param str $version human-readable *release* version: 1.7, 1.7.3
  * @return bool
  * @since 1.7.0
  */
@@ -1406,7 +1632,6 @@ function elgg_deprecated_notice($msg, $dep_version) {
 	// if it's a 2 minor releases behind, visual and logged
 	// if it's 1 minor release behind, logged.
 	// bugfixes don't matter because you're not deprecating between them, RIGHT?
-
 	if (!$dep_version) {
 		return FALSE;
 	}
@@ -1450,13 +1675,7 @@ function elgg_deprecated_notice($msg, $dep_version) {
 
 
 /**
- * Privilege elevation and gatekeeper code
- */
-
-
-/**
- * Gatekeeper function which ensures that a we are being executed from
- * a specified location.
+ * Checks if code is being called from a certain function.
  *
  * To use, call this function with the function name (and optional file location) that it has to be called
  * from, it will either return true or false.
@@ -1486,6 +1705,7 @@ function elgg_deprecated_notice($msg, $dep_version) {
  * @param mixed $function The function that this function must have in its call stack,
  * 		to test against a method pass an array containing a class and method name.
  * @param string $file Optional file that the function must reside in.
+ * @todo This is neat but is it necessary?
  */
 function call_gatekeeper($function, $file = "") {
 	// Sanity check
@@ -1516,7 +1736,6 @@ function call_gatekeeper($function, $file = "") {
 		return false;
 	}
 
-
 	// If file then check that this it is being called from this function
 	if ($file) {
 		$mirror = null;
@@ -1544,6 +1763,7 @@ function call_gatekeeper($function, $file = "") {
  * @param string $path The full path and filename that this function must have in its call stack If a partial path is given and $include_subdirs is true, then the function will return true if called by any function in or below the specified path.
  * @param bool $include_subdirs Are subdirectories of the path ok, or must you specify an absolute path and filename.
  * @param bool $strict_mode If true then the calling method or function must be directly called by something on $path, if false the whole call stack is searched.
+ * @todo Again, very neat, but is it necessary?
  */
 function callpath_gatekeeper($path, $include_subdirs = true, $strict_mode = false) {
 	global $CONFIG;
@@ -1590,7 +1810,9 @@ function callpath_gatekeeper($path, $include_subdirs = true, $strict_mode = fals
 }
 
 /**
- * Returns true or false depending on whether a PHP .ini setting is on or off
+ * Return the state of a php.ini setting.
+ *
+ * Normalizes the setting to bool.
  *
  * @param string $ini_get_arg The INI setting
  * @return true|false Depending on whether it's on or off
@@ -1605,10 +1827,13 @@ function ini_get_bool($ini_get_arg) {
 }
 
 /**
+ * Returns true is string is not empty, false, or null.
+ *
  * Function to be used in array_filter which returns true if $string is not null.
  *
  * @param string $string
  * @return bool
+ * @todo This is used once in metadata.php.  Use a lambda function instead.
  */
 function is_not_null($string) {
 	if (($string==='') || ($string===false) || ($string===null)) {
@@ -1620,11 +1845,13 @@ function is_not_null($string) {
 
 
 /**
- * Normalise the singular keys in an options array
- * to the plural keys.
+ * Normalise the singular keys in an options array to plural keys.
  *
- * @param $options
- * @param $singulars
+ * Used in elgg_get_entities*() functions to support shortcutting plural
+ * names by singular names.
+ *
+ * @param array $options The options array. $options['keys'] = 'values';
+ * @param array $singulars A list of sinular words to pluralize by adding 's'.
  * @return array
  * @since 1.7.0
  */
@@ -1647,15 +1874,18 @@ function elgg_normalise_plural_options_array($options, $singulars) {
 }
 
 /**
- * Get the full URL of the current page.
+ * Return the full URL of the current page.
  *
  * @return string The URL
+ * @todo Combine / replace with current_page_url()
  */
 function full_url() {
 	$s = empty($_SERVER["HTTPS"]) ? '' : ($_SERVER["HTTPS"] == "on") ? "s" : "";
 	$protocol = substr(strtolower($_SERVER["SERVER_PROTOCOL"]), 0, strpos(strtolower($_SERVER["SERVER_PROTOCOL"]), "/")) . $s;
 	$port = ($_SERVER["SERVER_PORT"] == "80" || $_SERVER["SERVER_PORT"] == "443") ? "" : (":".$_SERVER["SERVER_PORT"]);
 
+	// This is here to prevent XSS in poorly written browsers used by 80% of the population.
+	// {@trac [5813]}
 	$quotes = array('\'', '"');
 	$encoded = array('%27', '%22');
 
@@ -1675,6 +1905,8 @@ function full_url() {
  *  xxx.xxx.xxx.xxx/nn    (nn = # bits, cisco style -- i.e. /24 = class C)
  * Does not match:
  * xxx.xxx.xxx.xx[yyy-zzz]  (range, partial octets not supported)
+ *
+ * @todo not used at all.
  */
 function test_ip($range, $ip) {
 	$result = 1;
@@ -1737,10 +1969,9 @@ function test_ip($range, $ip) {
  * @param array $networks
  * @param string $ip
  * @return bool
+ * @todo not used at all in core.
  */
 function is_ip_in_array(array $networks, $ip) {
-	global $SYSTEM_LOG;
-
 	foreach ($networks as $network) {
 		if (test_ip(trim($network), $ip)) {
 			return true;
@@ -1753,7 +1984,9 @@ function is_ip_in_array(array $networks, $ip) {
 require_once dirname(dirname(__FILE__)).'/classes/Friendable.php';
 
 /**
- * Rebuilds a parsed (partial) URL
+ * Builds a URL from the a parts array like one returned by {@link parse_url()}.
+ *
+ * @note If only partial information is passed, a partial URL will be returned.
  *
  * @param array $parts Associative array of URL components like parse_url() returns
  * @param bool $htmlencode HTML Encode the url?
@@ -1777,14 +2010,22 @@ function elgg_http_build_url(array $parts, $html_encode = TRUE) {
 	}
 }
 
-
 /**
  * Adds action tokens to URL
  *
+ * As of 1.7.0 action tokens are required on all actions.
+ * Use this function to append action tokens to a URL's GET parameters.
+ * This will preserve any existing GET parameters.
+ *
+ * @note If you are using {@elgg_view input/form} you don't need to
+ * add tokens to the action.  The form view automatically handles
+ * tokens.
+ *
  * @param str $link Full action URL
  * @param bool $htmlencode html encode the url?
  * @return str URL with action tokens
  * @since 1.7.0
+ * @link http://docs.elgg.org/Tutorials/Actions
  */
 function elgg_add_action_tokens_to_url($url, $html_encode = TRUE) {
 	$components = parse_url($url);
@@ -1808,7 +2049,10 @@ function elgg_add_action_tokens_to_url($url, $html_encode = TRUE) {
 	return elgg_http_build_url($components, $html_encode);
 }
 
+
 /**
+ * Add action tokens to URL.
+ *
  * @deprecated 1.7 final
  */
 function elgg_validate_action_url($url) {
@@ -1817,12 +2061,15 @@ function elgg_validate_action_url($url) {
 	return elgg_add_action_tokens_to_url($url);
 }
 
+
 /**
- * Removes a single elementry from a (partial) url query.
+ * Removes an element from a URL's query string.
+ *
+ * @note You can send a partial URL string.
  *
  * @param string $url
  * @param string $element
- * @return string
+ * @return string The new URL with the query element removed.
  * @since 1.7.0
  */
 function elgg_http_remove_url_query_element($url, $element) {
@@ -1844,13 +2091,12 @@ function elgg_http_remove_url_query_element($url, $element) {
 	return $string;
 }
 
-
 /**
- * Adds get params to $url
+ * Adds an element or elements to a URL's query string.
  *
- * @param str $url
- * @param array $elements k/v pairs.
- * @return str
+ * @param str $url The URL
+ * @param array $elements key/value pairs to add to the URL
+ * @return str The new URL with the query strings added
  * @since 1.7.0
  */
 function elgg_http_add_url_query_elements($url, array $elements) {
@@ -1872,16 +2118,12 @@ function elgg_http_add_url_query_elements($url, array $elements) {
 	return $string;
 }
 
-
 /**
- * Breadcrumb support.
- */
-
-/**
- * Adds a breadcrumb to the stack
+ * Adds a breadcrumb to the breadcrumbs stack.
  *
  * @param string $title The title to display
  * @param string $link Optional. The link for the title.
+ * @link http://docs.elgg.org/Tutorials/UI/Breadcrumbs
  */
 function elgg_push_breadcrumb($title, $link = NULL) {
 	global $CONFIG;
@@ -1897,6 +2139,7 @@ function elgg_push_breadcrumb($title, $link = NULL) {
  * Removes last breadcrumb entry.
  *
  * @return array popped item.
+ * @link http://docs.elgg.org/Tutorials/UI/Breadcrumbs
  */
 function elgg_pop_breadcrumb() {
 	global $CONFIG;
@@ -1909,9 +2152,10 @@ function elgg_pop_breadcrumb() {
 }
 
 /**
- * Returns all breadcrumbs
+ * Returns all breadcrumbs as an array of array('title' => 'Readable Title', 'link' => 'URL')
  *
  * @return array Breadcrumbs
+ * @link http://docs.elgg.org/Tutorials/UI/Breadcrumbs
  */
 function elgg_get_breadcrumbs() {
 	global $CONFIG;
@@ -1919,16 +2163,13 @@ function elgg_get_breadcrumbs() {
 	return (is_array($CONFIG->breadcrumbs)) ? $CONFIG->breadcrumbs : array();
 }
 
-
-/**
- * Sticky forms
- */
-
 /**
  * Load all the REQUEST variables into the sticky form cache
  *
  * Call this from an action when you want all your submitted variables
  * available if the submission fails validation and is sent back to the form
+ *
+ * @link http://docs.elgg.org/Tutorials/UI/StickyForms
  */
 function elgg_make_sticky_form($form_name) {
 	global $CONFIG;
@@ -1947,7 +2188,6 @@ function elgg_make_sticky_form($form_name) {
 	}
 }
 
-
 /**
  * Clear the sticky form cache
  *
@@ -1956,23 +2196,25 @@ function elgg_make_sticky_form($form_name) {
  * after a validation error.
  *
  * @param string $name Form namespace
+ * @link http://docs.elgg.org/Tutorials/UI/StickyForms
  */
 function elgg_clear_sticky_form($form_name) {
 	unset($_SESSION['sticky_forms'][$form_name]);
 }
 
 /**
- * Has this form been made sticky
+ * Has this form been made sticky?
  *
  * @param string $name Form namespace
  * @return boolean
+ * @link http://docs.elgg.org/Tutorials/UI/StickyForms
  */
 function elgg_is_sticky_form($form_name) {
 	return isset($_SESSION['sticky_forms'][$form_name]);
 }
 
 /**
- * Get a specific stick variable
+ * Get a specific sticky variable
  *
  * @param string $variable The name of the variable
  * @param mixed $default Default value if the variable does not exist in sticky cache
@@ -1980,6 +2222,7 @@ function elgg_is_sticky_form($form_name) {
  * @return mixed
  *
  * @todo should this filter the default value?
+ * @link http://docs.elgg.org/Tutorials/UI/StickyForms
  */
 function elgg_get_sticky_value($form_name, $variable, $default = NULL, $filter_result = true) {
 	if (isset($_SESSION['sticky_forms'][$form_name][$variable])) {
@@ -1997,6 +2240,7 @@ function elgg_get_sticky_value($form_name, $variable, $default = NULL, $filter_r
  * Clear a specific sticky variable
  *
  * @param string $variable The name of the variable to clear
+ * @link http://docs.elgg.org/Tutorials/UI/StickyForms
  */
 function elgg_clear_sticky_value($form_name, $variable) {
 	unset($_SESSION['sticky_forms'][$form_name][$variable]);
@@ -2005,6 +2249,7 @@ function elgg_clear_sticky_value($form_name, $variable) {
 /**
  * Returns the current active sticky form.
  * @return mixed Str | FALSE
+ * @link http://docs.elgg.org/Tutorials/UI/StickyForms
  */
 function elgg_get_active_sticky_form() {
 	global $CONFIG;
@@ -2018,13 +2263,22 @@ function elgg_get_active_sticky_form() {
 	return (elgg_is_sticky_form($form_name)) ? $form_name : FALSE;
 }
 
+/**
+ * Sets the active sticky form.
+ *
+ * @param string $form_name
+ * @link http://docs.elgg.org/Tutorials/UI/StickyForms
+ */
 function elgg_set_active_sticky_form($form_name) {
 	global $CONFIG;
 
 	$CONFIG->active_sticky_form = $form_name;
 }
+
 /**
- * Returns the PHP INI setting in bytes
+ * Returns a PHP INI setting in bytes.
+ *
+ * @tip Use this for arithmetic when determining if a file can be uploaded.
  *
  * @param str $setting
  * @return int
@@ -2051,10 +2305,14 @@ function elgg_get_ini_setting_in_bytes($setting) {
 }
 
 /**
- * Server javascript pages.
+ * Serve javascript pages.
+ *
+ * Searches for views under js/ and outputs them with special
+ * headers for caching control.
  *
  * @param $page
  * @return unknown_type
+ * @elgg_pagehandler js
  */
 function js_page_handler($page) {
 	if (is_array($page) && sizeof($page)) {
@@ -2073,9 +2331,14 @@ function js_page_handler($page) {
 }
 
 /**
- * This function is a shutdown hook registered on startup which does nothing more than trigger a
- * shutdown event when the script is shutting down, but before database connections have been dropped etc.
+ * Emits a shutdown:system event upon PHP shutdown, but before database connections are dropped.
+ *
+ * @tip Register for the shutdown:system event to perform functions at the end of page loads.
+ *
+ * @warning Using this event to perform long-running functions is not very useful.  Servers will hold pages until processing is done
+ * before sending them out to the browser.
  *
+ * @see register_shutdown_hook()
  */
 function __elgg_shutdown_hook() {
 	global $START_MICROTIME;
@@ -2088,28 +2351,31 @@ function __elgg_shutdown_hook() {
 }
 
 /**
- * Register functions for Elgg core
+ * Elgg's main init.
  *
- * @return unknown_type
+ * Handles core actions for comments and likes, the JS pagehandler, and the shutdown function.
+ *
+ * @elgg_event_handler init system
  */
 function elgg_init() {
 	global $CONFIG;
 
-	// Actions
 	register_action('comments/add');
 	register_action('comments/delete');
 	register_action('likes/add');
 	register_action('likes/delete');
 
-	// Page handler for JS
-	register_page_handler('js','js_page_handler');
+	register_page_handler('js', 'js_page_handler');
 
-	// Register an event triggered at system shutdown
+	// Trigger the shutdown:system event upon PHP shutdown.
 	register_shutdown_function('__elgg_shutdown_hook');
 }
 
 /**
- * Walled garden system:index plugin hook.
+ * Intercepts the index page when Walled Garden mode is enabled.
+ *
+ * @link http://docs.elgg.org/Tutorials/WalledGarden
+ * @elgg_plugin_hook index system
  */
 function elgg_walled_garden_index() {
 	$login = elgg_view('account/forms/login_walled_garden');
@@ -2121,7 +2387,9 @@ function elgg_walled_garden_index() {
 }
 
 /**
- * Runs unit tests for the API.
+ * Adds unit tests for the general API.
+ *
+ * @elgg_plugin_hook unit_tests system
  */
 function elgg_api_test($hook, $type, $value, $params) {
 	global $CONFIG;
@@ -2132,9 +2400,14 @@ function elgg_api_test($hook, $type, $value, $params) {
 }
 
 /**
- * Sorts out the featured URLs and the "more" dropdown
+ * Returns the main site menu.
+ *
+ * @note The main site menu is split into "featured" links and
+ * "more" links.
+ *
  * @return array ('featured_urls' and 'more')
  * @since 1.8
+ * @link http://docs.elgg.org/Tutorials/UI/SiteMenu
  */
 function elgg_get_nav_items() {
 	$menu_items = get_register('menu');
@@ -2152,7 +2425,7 @@ function elgg_get_nav_items() {
 
 	// make sure the url is a valid link.
 	// this prevents disabled plugins leaving behind
-	// valid links when no using a pagehandler.
+	// valid links when not using a pagehandler.
 	foreach ($featured_urls_info as $info) {
 		if (in_array($info->value->url, $valid_urls)) {
 			$featured_urls[] = $info->value->url;
@@ -2174,8 +2447,14 @@ function elgg_get_nav_items() {
 }
 
 /**
- * Hook that registers the custom menu items.
+ * Registers any custom menu items with the main Site Menu.
+ *
+ * @note Custom menu items are added through the admin interface.  Plugins
+ * can add standard menu items by using {@link add_menu()}.
+ *
  * @since 1.8
+ * @link http://docs.elgg.org/Tutorials/UI/SiteMenu
+ * @elgg_event_handler init system
  */
 function add_custom_menu_items() {
 	if ($custom_items = get_config('menu_items_custom_items')) {
@@ -2186,7 +2465,11 @@ function add_custom_menu_items() {
 }
 
 /**
- * Test two URLs to see if they are functionally identical.
+ * Test if two URLs are functionally identical.
+ *
+ * @tip If $ignore_params is used, neither the name nor its value will be considered when comparing.
+ *
+ * @tip The order of GET params doesn't matter.
  *
  * @param string $url1
  * @param string $url2
@@ -2277,9 +2560,16 @@ function elgg_http_url_is_identical($url1, $url2, $ignore_params = array('offset
 }
 
 /**
- * Checks walled garden status upon Elgg init.
+ * Checks the status of the Walled Garden and forwards to a login page
+ * if required.
+ *
+ * If the site is in Walled Garden mode, all page except those registered as
+ * plugin pages by {@elgg_hook public_pages walled_garden} will redirect to
+ * a login page.
  *
  * @since 1.8
+ * @elgg_event_handler init system
+ * @link http://docs.elgg.org/Tutorials/WalledGarden
  */
 function elgg_walled_garden() {
 	global $CONFIG;
@@ -2307,8 +2597,10 @@ function elgg_get_array_value($key, array $array, $default = NULL) {
 
 /**
  * Sorts a 3d array by specific element.
- * Will re-index numeric indexes.
- * NB: This operates the same as the built-in sort functions.
+ *
+ * @warning Will re-index numeric indexes.
+ *
+ * @note This operates the same as the built-in sort functions.
  * ie, sorts the array and returns a bool for success.
  *
  * Do this: elgg_sort_3d_array_by_value($my_array);
@@ -2334,29 +2626,58 @@ function elgg_sort_3d_array_by_value(&$array, $element, $sort_order = SORT_ASC,
 	return array_multisort($sort, $sort_order, $sort_type, $array);
 }
 
-/**
- * Some useful constant definitions
+
+/**#@+
+ * Controlls access levels on ElggEntity entities, metadata, and annotations.
+ *
+ * @var int
  */
 define('ACCESS_DEFAULT', -1);
 define('ACCESS_PRIVATE', 0);
 define('ACCESS_LOGGED_IN', 1);
 define('ACCESS_PUBLIC', 2);
 define('ACCESS_FRIENDS', -2);
+/**#@-*/
 
 /**
- * @since 1.7.0
+ * Constant to request the value of a parameter be ignored in elgg_get_*() functions
+ *
+ * @see elgg_get_entities()
+ * @var NULL
+ * @since 1.7
  */
 define('ELGG_ENTITIES_ANY_VALUE', NULL);
+
+/**
+ * Constant to request the value of a parameter be nothing in elgg_get_*() functions.
+ *
+ * @see elgg_get_entities()
+ * @var int 0
+ * @since 1.7
+ */
 define('ELGG_ENTITIES_NO_VALUE', 0);
 
 /**
- * @since 1.7.2
+ * Used in calls to forward() to specify the browser should be redirected to the
+ * referring page.
+ *
+ * @see forward
+ * @var unknown_type
  */
 define('REFERRER', -1);
+
+/**
+ * Alternate spelling for REFERRER.  Included because of some bad documentation
+ * in the original HTTP spec.
+ *
+ * @see forward()
+ * @link http://en.wikipedia.org/wiki/HTTP_referrer#Origin_of_the_term_referer
+ * @var int -1
+ */
 define('REFERER', -1);
 
 register_elgg_event_handler('init', 'system', 'elgg_init');
 register_plugin_hook('unit_test', 'system', 'elgg_api_test');
 
 register_elgg_event_handler('init', 'system', 'add_custom_menu_items', 1000);
-register_elgg_event_handler('init', 'system', 'elgg_walled_garden', 1000);
+register_elgg_event_handler('init', 'system', 'elgg_walled_garden', 1000);
\ No newline at end of file