Merged r6757:6810 from 1.7 branch into trunk

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

31 files changed, 126 insertions, 66 deletions

diff --git a/engine/lib/access.php b/engine/lib/access.php
index b8d8820e1..39f7925c6 100644
--- a/engine/lib/access.php
+++ b/engine/lib/access.php
@@ -188,7 +188,7 @@ function get_default_access(ElggUser $user = null) {
  * Override the default behaviour and allow results to show hidden entities as well.
  * THIS IS A HACK.
  *
- * TODO: Replace this with query object!
+ * @todo Replace this with query object!
  */
 $ENTITY_SHOW_HIDDEN_OVERRIDE = false;
 
@@ -216,13 +216,13 @@ function access_get_show_hidden_status() {
  * Returns an SQL fragment that is true (or optionally false) if the given user has
  * added an annotation with the given name to the given entity.
  *
- * TODO: This is fairly generic so perhaps it could be moved to annotations.php
+ * @todo This is fairly generic so perhaps it could be moved to annotations.php
  *
  * @param string $annotation_name name of the annotation
-	* @param string $entity_guid SQL string that evaluates to the GUID of the entity the annotation should be attached to
-	* @param string $owner_guid SQL string that evaluates to the GUID of the owner of the annotation	 	 *
-	* @param boolean $exists If set to true, will return true if the annotation exists, otherwise returns false
-	* @return string An SQL fragment suitable for inserting into a WHERE clause
+ * @param string $entity_guid SQL string that evaluates to the GUID of the entity the annotation should be attached to
+ * @param string $owner_guid SQL string that evaluates to the GUID of the owner of the annotation	 	 *
+ * @param boolean $exists If set to true, will return true if the annotation exists, otherwise returns false
+ * @return string An SQL fragment suitable for inserting into a WHERE clause
  */
 function get_annotation_sql($annotation_name, $entity_guid, $owner_guid, $exists) {
 	global $CONFIG;
@@ -246,7 +246,7 @@ END;
 /**
  * Add access restriction sql code to a given query.
  * Note that if this code is executed in privileged mode it will return blank.
- * @TODO: DELETE once Query classes are fully integrated
+ * @todo DELETE once Query classes are fully integrated
  *
  * @param string $table_prefix Optional table. prefix for the access code.
  * @param int $owner
@@ -734,7 +734,7 @@ function get_entities_from_access_id($collection_id, $entity_type = "", $entity_
  * @param int $collection_id
  * @param array $options @see elgg_get_entities()
  * @return array
- * @since 1.7
+ * @since 1.7.0
  */
 function elgg_get_entities_from_access_id(array $options=array()) {
 	// restrict the resultset to access collection provided
@@ -785,7 +785,8 @@ function list_entities_from_access_id($collection_id, $entity_type = "", $entity
  *
  * @param $entity_accessid (int) The entity's access id
  * @return string e.g. Public, Private etc
- **/
+ * @since 1.7.0
+ */
 function get_readable_access_level($entity_accessid){
 	$access = (int) $entity_accessid;
 	//get the access level for object in readable string
@@ -804,6 +805,7 @@ function get_readable_access_level($entity_accessid){
  * Set if entity access system should be ignored.
  *
  * @return bool Previous ignore_access setting.
+ * @since 1.7.0
  */
 function elgg_set_ignore_access($ignore = true) {
 	$elgg_access = elgg_get_access_object();
@@ -814,6 +816,7 @@ function elgg_set_ignore_access($ignore = true) {
  * Get current ignore access setting.
  *
  * @return bool
+ * @since 1.7.0
  */
 function elgg_get_ignore_access() {
 	return elgg_get_access_object()->get_ignore_access();
@@ -823,6 +826,7 @@ function elgg_get_ignore_access() {
  * Decides if the access system is being ignored.
  *
  * @return bool
+ * @since 1.7.0
  */
 function elgg_check_access_overrides($user_guid = null) {
 	if (!$user_guid || $user_guid <= 0) {
@@ -838,6 +842,7 @@ function elgg_check_access_overrides($user_guid = null) {
  * Returns the ElggAccess object.
  *
  * @return ElggAccess
+ * @since 1.7.0
  */
 function elgg_get_access_object() {
 	static $elgg_access;
@@ -865,6 +870,7 @@ function access_init() {
  * Override permissions system
  *
  * @return true|null
+ * @since 1.7.0
  */
 function elgg_override_permissions_hook($hook, $type, $returnval, $params) {
 	$user_guid = get_loggedin_userid();
diff --git a/engine/lib/actions.php b/engine/lib/actions.php
index 47c0bf7af..c7abd5f18 100644
--- a/engine/lib/actions.php
+++ b/engine/lib/actions.php
@@ -54,14 +54,15 @@ function action($action, $forwarder = "") {
 		if ((isadminloggedin()) || (!$CONFIG->actions[$action]['admin'])) {
 			if ($CONFIG->actions[$action]['public'] || get_loggedin_userid()) {
 
-				// Trigger action event TODO: This is only called before the primary action is called. We need to rethink actions for 1.5
+				// Trigger action event
+				// @todo This is only called before the primary action is called. We need to rethink actions for 1.5
 				$event_result = true;
 				$event_result = trigger_plugin_hook('action', $action, null, $event_result);
 
 				// Include action
 				// Event_result being false doesn't produce an error -
 				// since i assume this will be handled in the hook itself.
-				// TODO make this better!
+				// @todo make this better!
 				if ($event_result) {
 					if (!include($CONFIG->actions[$action]['file'])) {
 						register_error(sprintf(elgg_echo('actionundefined'),$action));
diff --git a/engine/lib/annotations.php b/engine/lib/annotations.php
index c960da014..dcb29d0ab 100644
--- a/engine/lib/annotations.php
+++ b/engine/lib/annotations.php
@@ -450,6 +450,7 @@ $value = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "asc", $time
  *  annotation_owner_guids => NULL|ARR guids for annotaiton owners
  *
  * @return array
+ * @since 1.7.0
  */
 function elgg_get_entities_from_annotations(array $options = array()) {
 	$defaults = array(
diff --git a/engine/lib/api.php b/engine/lib/api.php
index a3869d262..823774108 100644
--- a/engine/lib/api.php
+++ b/engine/lib/api.php
@@ -389,6 +389,7 @@ function expose_function($method, $function, array $parameters = NULL, $descript
 /**
  * Unregister an API method
  * @param string $method The api name that was exposed
+ * @since 1.7.0
  */
 function unexpose_function($method) {
 	global $API_METHODS;
@@ -403,6 +404,7 @@ function unexpose_function($method) {
  * @param string $method The api name that was exposed
  * @return true or throws an exception
  * @throws APIException
+ * @since 1.7.0
  */
 function authenticate_method($method) {
 	global $API_METHODS;
@@ -557,6 +559,7 @@ function get_post_data() {
 
 /**
  * This fixes the post parameters that are munged due to page handler
+ * @since 1.7.0
  */
 function include_post_data() {
 
@@ -578,6 +581,7 @@ function include_post_data() {
  * @param $parameters
  * @return true on success or exception
  * @throws APIException
+ * @since 1.7.0
  */
 function verify_parameters($method, $parameters) {
 	global $API_METHODS;
@@ -610,6 +614,7 @@ function verify_parameters($method, $parameters) {
  * @param array $parameters Array of parameters
  * @return string or exception
  * @throws APIException
+ * @since 1.7.0
  */
 function serialise_parameters($method, $parameters) {
 	global $API_METHODS;
@@ -688,6 +693,7 @@ function serialise_parameters($method, $parameters) {
  * PAM: Confirm that the call includes a valid API key
  * @return true if good API key - otherwise throws exception
  * @throws APIException
+ * @since 1.7.0
  */
 function api_auth_key() {
 	global $CONFIG;
@@ -715,6 +721,7 @@ function api_auth_key() {
  * PAM: Confirm the HMAC signature
  * @return true if success - otherwise throws exception
  * @throws SecurityException
+ * @since 1.7.0
  */
 function api_auth_hmac() {
 	global $CONFIG;
@@ -850,7 +857,7 @@ function get_and_validate_api_headers() {
 function map_api_hash($algo) {
 	$algo = strtolower(sanitise_string($algo));
 	$supported_algos = array(
-		"md5" => "md5",	// TODO: Consider phasing this out
+		"md5" => "md5",	// @todo Consider phasing this out
 		"sha" => "sha1", // alias for sha1
 		"sha1" => "sha1",
 		"sha256" => "sha256"
@@ -897,7 +904,7 @@ function calculate_hmac($algo, $time, $nonce, $api_key, $secret_key, $get_variab
 /**
  * Calculate a hash for some post data.
  *
- * TODO: Work out how to handle really large bits of data.
+ * @todo Work out how to handle really large bits of data.
  *
  * @param string $postdata string The post data.
  * @param string $algo The algorithm used.
@@ -1094,6 +1101,7 @@ function create_user_token($username, $expire = 60) {
  * @param int $site_guid The ID of the site (default is current site)
  * @return false if none available or array of stdClass objects
  * 		(see users_apisessions schema for available variables in objects)
+ * @since 1.7.0
  */
 function get_user_tokens($user_guid, $site_guid) {
 	global $CONFIG;
@@ -1149,6 +1157,7 @@ function validate_user_token($token, $site_guid) {
  * @param string $token
  * @param int $site_guid The ID of the site (default is current site)
  * @return bool
+ * @since 1.7.0
  */
 function remove_user_token($token, $site_guid) {
 	global $CONFIG;
@@ -1168,6 +1177,7 @@ function remove_user_token($token, $site_guid) {
  * Remove expired tokens
  *
  * @return bool
+ * @since 1.7.0
  */
 function remove_expired_user_tokens() {
 	global $CONFIG;
@@ -1474,6 +1484,7 @@ function service_handler($handler, $request) {
  * @param string $handler web services type
  * @param string $function Your function name
  * @return true|false Depending on success
+ * @since 1.7.0
  */
 function register_service_handler($handler, $function) {
 	global $CONFIG;
@@ -1494,6 +1505,7 @@ function register_service_handler($handler, $function) {
  * with register_service_handler().
  *
  * @param string $handler web services type
+ * @return 1.7.0
  */
 function unregister_service_handler($handler) {
 	global $CONFIG;
diff --git a/engine/lib/cache.php b/engine/lib/cache.php
index df7b1e525..e227ba770 100644
--- a/engine/lib/cache.php
+++ b/engine/lib/cache.php
@@ -332,7 +332,7 @@ class ElggFileCache extends ElggCache {
 	 * @param string $filename
 	 */
 	protected function sanitise_filename($filename) {
-		// TODO : Writeme
+		// @todo : Writeme
 
 		return $filename;
 	}
@@ -397,11 +397,11 @@ class ElggFileCache extends ElggCache {
 	}
 
 	public function clear() {
-		// TODO : writeme
+		// @todo writeme
 	}
 
 	public function __destruct() {
-		// TODO: Check size and age, clean up accordingly
+		// @todo Check size and age, clean up accordingly
 		$size = 0;
 		$dir = $this->get_variable("cache_path");
 
@@ -430,7 +430,7 @@ class ElggFileCache extends ElggCache {
 					unlink($dir.$f);
 				}
 
-				// TODO: Size
+				// @todo Size
 			}
 		}
 	}
diff --git a/engine/lib/database.php b/engine/lib/database.php
index c8945e2d1..798f3ef59 100644
--- a/engine/lib/database.php
+++ b/engine/lib/database.php
@@ -577,7 +577,7 @@ function db_upgrade($version, $fromdir = "", $quiet = FALSE) {
  * This function, called by validate_platform(), will check whether the installed version of
  * MySQL meets the minimum required.
  *
- * TODO: If multiple dbs are supported check which db is supported and use the appropriate code to validate
+ * @todo If multiple dbs are supported check which db is supported and use the appropriate code to validate
  * the appropriate version.
  *
  * @return bool
diff --git a/engine/lib/elgglib.php b/engine/lib/elgglib.php
index 1d52c0534..9a09d4f72 100644
--- a/engine/lib/elgglib.php
+++ b/engine/lib/elgglib.php
@@ -85,8 +85,8 @@ function current_page_url() {
 /**
  * This is a factory function which produces an ElggCache object suitable for caching file load paths.
  *
- * TODO: Can this be done in a cleaner way?
- * TODO: Swap to memcache etc?
+ * @todo Can this be done in a cleaner way?
+ * @todo Swap to memcache etc?
  */
 function elgg_get_filepath_cache() {
 	global $CONFIG;
@@ -654,6 +654,7 @@ function add_to_register($register_name, $subregister_name, $subregister_value,
  * @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
  */
 function remove_from_register($register_name, $subregister_name) {
 	global $CONFIG;
@@ -963,6 +964,7 @@ function register_elgg_event_handler($event, $object_type, $function, $priority
  * @param string $event The event type
  * @param string $object_type The object type
  * @param string $function The function name
+ * @since 1.7.0
  */
 function unregister_elgg_event_handler($event, $object_type, $function) {
 	global $CONFIG;
@@ -1046,6 +1048,7 @@ function register_plugin_hook($hook, $type, $function, $priority = 500) {
  * @param string $hook The name of the hook
  * @param string $entity_type The name of the type of entity (eg "user", "object" etc)
  * @param string $function The name of a valid function to be run
+ * @since 1.7.0
  */
 function unregister_plugin_hook($hook, $entity_type, $function) {
 	global $CONFIG;
@@ -1130,7 +1133,7 @@ function __elgg_php_error_handler($errno, $errmsg, $filename, $linenum, $vars) {
 
 	switch ($errno) {
 		case E_USER_ERROR:
-			error_log("ERROR: $error");
+			error_log("PHP ERROR: $error");
 			register_error("ERROR: $error");
 
 			// Since this is a fatal error, we want to stop any further execution but do so gracefully.
@@ -1139,13 +1142,13 @@ function __elgg_php_error_handler($errno, $errmsg, $filename, $linenum, $vars) {
 
 		case E_WARNING :
 		case E_USER_WARNING :
-			error_log("WARNING: $error");
+			error_log("PHP WARNING: $error");
 			break;
 
 		default:
 			global $CONFIG;
 			if (isset($CONFIG->debug) && $CONFIG->debug === 'NOTICE') {
-				error_log("NOTICE: $error");
+				error_log("PHP NOTICE: $error");
 			}
 	}
 
@@ -1164,6 +1167,7 @@ function __elgg_php_error_handler($errno, $errmsg, $filename, $linenum, $vars) {
  * @param str $message User message
  * @param str $level NOTICE | WARNING | ERROR | DEBUG
  * @return bool
+ * @since 1.7.0
  */
 function elgg_log($message, $level='NOTICE') {
 	global $CONFIG;
@@ -1211,6 +1215,7 @@ function elgg_log($message, $level='NOTICE') {
  * @param bool $to_screen
  * @param string $level
  * @return void
+ * @since 1.7.0
  */
 function elgg_dump($value, $to_screen = TRUE, $level = 'NOTICE') {
 	global $CONFIG;
@@ -1394,6 +1399,7 @@ function run_function_once($functionname, $timelastupdatedcheck = 0) {
  * @param str $version human-readable *release* version the function was deprecated. No bloody A, B, (R)C, or D.
  *
  * @return bool
+ * @since 1.7.0
  */
 function elgg_deprecated_notice($msg, $dep_version) {
 	// if it's a major release behind, visual and logged
@@ -1620,6 +1626,7 @@ function is_not_null($string) {
  * @param $options
  * @param $singulars
  * @return array
+ * @since 1.7.0
  */
 function elgg_normalise_plural_options_array($options, $singulars) {
 	foreach ($singulars as $singular) {
@@ -1659,7 +1666,7 @@ function full_url() {
  * Useful function found in the comments on the PHP man page for ip2long.
  * Returns 1 if an IP matches a given range.
  *
- * TODO: Check licence... assuming this is PD since it was found several places on the interwebs..
+ * @todo Check licence... assuming this is PD since it was found several places on the interwebs..
  * please check or rewrite.
  *
  * Matches:
@@ -1832,7 +1839,7 @@ interface Friendable {
  * @param array $parts Associative array of URL components like parse_url() returns
  * @param bool $htmlencode HTML Encode the url?
  * @return str Full URL
- * @since 1.7
+ * @since 1.7.0
  */
 function elgg_http_build_url(array $parts, $html_encode = TRUE) {
 	// build only what's given to us.
@@ -1858,7 +1865,7 @@ function elgg_http_build_url(array $parts, $html_encode = TRUE) {
  * @param str $link Full action URL
  * @param bool $htmlencode html encode the url?
  * @return str URL with action tokens
- * @since 1.7
+ * @since 1.7.0
  */
 function elgg_add_action_tokens_to_url($url, $html_encode = TRUE) {
 	$components = parse_url($url);
@@ -1897,6 +1904,7 @@ function elgg_validate_action_url($url) {
  * @param string $url
  * @param string $element
  * @return string
+ * @since 1.7.0
  */
 function elgg_http_remove_url_query_element($url, $element) {
 	$url_array = parse_url($url);
@@ -1924,6 +1932,7 @@ function elgg_http_remove_url_query_element($url, $element) {
  * @param str $url
  * @param array $elements k/v pairs.
  * @return str
+ * @since 1.7.0
  */
 function elgg_http_add_url_query_elements($url, array $elements) {
 	$url_array = parse_url($url);
@@ -2100,7 +2109,7 @@ function elgg_set_active_sticky_form($form_name) {
  *
  * @param str $setting
  * @return int
- * @since 1.7
+ * @since 1.7.0
  * @link http://www.php.net/manual/en/function.ini-get.php
  */
 function elgg_get_ini_setting_in_bytes($setting) {
@@ -2416,7 +2425,7 @@ define('ACCESS_PUBLIC', 2);
 define('ACCESS_FRIENDS', -2);
 
 /**
- * @since 1.7
+ * @since 1.7.0
  */
 define('ELGG_ENTITIES_ANY_VALUE', NULL);
 define('ELGG_ENTITIES_NO_VALUE', 0);
diff --git a/engine/lib/entities.php b/engine/lib/entities.php
index e6c2baa8e..9b3895fd5 100644
--- a/engine/lib/entities.php
+++ b/engine/lib/entities.php
@@ -15,7 +15,8 @@ $ENTITY_CACHE = NULL;
 /// Cache subtype searches
 $SUBTYPE_CACHE = NULL;
 
-/// Require the locatable interface TODO: Move this into start.php?
+/// Require the locatable interface
+// @todo Move this into start.php?
 require_once('location.php');
 
 /**
@@ -781,7 +782,8 @@ abstract class ElggEntity implements
 				throw new IOException(elgg_echo('IOException:BaseEntitySaveFailed'));
 			}
 
-			// Save any unsaved metadata TODO: How to capture extra information (access id etc)
+			// Save any unsaved metadata
+			// @todo How to capture extra information (access id etc)
 			if (sizeof($this->temp_metadata) > 0) {
 				foreach($this->temp_metadata as $name => $value) {
 					$this->$name = $value;
@@ -789,7 +791,8 @@ abstract class ElggEntity implements
 				}
 			}
 
-			// Save any unsaved annotations metadata. TODO: How to capture extra information (access id etc)
+			// Save any unsaved annotations metadata.
+			// @todo How to capture extra information (access id etc)
 			if (sizeof($this->temp_annotations) > 0) {
 				foreach($this->temp_annotations as $name => $value) {
 					$this->annotate($name, $value);
@@ -1233,7 +1236,7 @@ function initialise_entity_cache() {
 	global $ENTITY_CACHE;
 
 	if (!$ENTITY_CACHE) {
-		//select_default_memcache('entity_cache'); // TODO: Replace with memcache?
+		//select_default_memcache('entity_cache'); // @todo Replace with memcache?
 		$ENTITY_CACHE = array();
 	}
 }
@@ -1306,7 +1309,7 @@ function retrieve_cached_entity_row($guid) {
 /**
  * Return the integer ID for a given subtype, or false.
  *
- * TODO: Move to a nicer place?
+ * @todo Move to a nicer place?
  *
  * @param string $type
  * @param string $subtype
@@ -1342,7 +1345,7 @@ function get_subtype_id($type, $subtype) {
 /**
  * For a given subtype ID, return its identifier text.
  *
- * TODO: Move to a nicer place?
+ * @todo Move to a nicer place?
  *
  * @param int $subtype_id
  */
@@ -1791,6 +1794,7 @@ function get_entity($guid) {
  *
  * @return 	if count, int
  * 			if not count, array or false if no entities
+ * @since 1.7.0
  */
 function elgg_get_entities(array $options = array()) {
 	global $CONFIG;
@@ -2026,6 +2030,7 @@ $count = false, $site_guid = 0, $container_guid = null, $timelower = 0, $timeupp
  * @param NULL|array $subtypes
  * @param NULL|array $pairs
  * @return FALSE|string
+ * @since 1.7.0
  */
 function elgg_get_entity_type_subtype_where_sql($table, $types, $subtypes, $pairs) {
 	// subtype depends upon type.
@@ -2179,6 +2184,7 @@ function elgg_get_entity_type_subtype_where_sql($table, $types, $subtypes, $pair
  * @param str $table
  * @param NULL|array $owner_guids
  * @return FALSE|str
+ * @since 1.7.0
  */
 function elgg_get_entity_owner_where_sql($table, $owner_guids) {
 	// short circuit if nothing requested
@@ -2216,6 +2222,7 @@ function elgg_get_entity_owner_where_sql($table, $owner_guids) {
  * @param string $table entity table prefix
  * @param NULL|array $container_guids
  * @return FALSE|string
+ * @since 1.7.0
  */
 function elgg_get_entity_container_where_sql($table, $container_guids) {
 	// short circuit if nothing is requested.
@@ -2257,6 +2264,7 @@ function elgg_get_entity_container_where_sql($table, $container_guids) {
  * @param NULL|int $time_updated_lower
  *
  * @return FALSE|str FALSE on fail, string on success.
+ * @since 1.7.0
  */
 function elgg_get_entity_time_where_sql($table, $time_created_upper = NULL, $time_created_lower = NULL,
 	$time_updated_upper = NULL, $time_updated_lower = NULL) {
@@ -2294,6 +2302,7 @@ function elgg_get_entity_time_where_sql($table, $time_created_upper = NULL, $tim
  * @param string $table entity table name
  * @param NULL|array $site_guids
  * @return FALSE|string
+ * @since 1.7.0
  */
 function elgg_get_entity_site_where_sql($table, $site_guids) {
 	// short circuit if nothing requested
@@ -2334,6 +2343,7 @@ function elgg_get_entity_site_where_sql($table, $site_guids) {
  * 	pagination => BOOL Display pagination links
  *
  * @return str
+ * @since 1.7.0
  */
 function elgg_list_entities($options) {
 	$defaults = array(
@@ -2526,7 +2536,8 @@ function disable_entity($guid, $reason = "", $recursive = true) {
 				}
 
 				if ($recursive) {
-					// Temporary token overriding access controls TODO: Do this better.
+					// Temporary token overriding access controls
+					// @todo Do this better.
 					static $__RECURSIVE_DELETE_TOKEN;
 					// Make it slightly harder to guess
 					$__RECURSIVE_DELETE_TOKEN = md5(get_loggedin_userid());
@@ -2612,7 +2623,8 @@ function delete_entity($guid, $recursive = true) {
 
 				// Delete contained owned and otherwise releated objects (depth first)
 				if ($recursive) {
-					// Temporary token overriding access controls TODO: Do this better.
+					// Temporary token overriding access controls
+					// @todo Do this better.
 					static $__RECURSIVE_DELETE_TOKEN;
 					// Make it slightly harder to guess
 					$__RECURSIVE_DELETE_TOKEN = md5(get_loggedin_userid());
@@ -3245,6 +3257,7 @@ function list_registered_entities($owner_guid = 0, $limit = 10, $fullview = true
  * 	pagination => BOOL Display pagination links
  *
  * @return string A viewable list of entities
+ * @since 1.7.0
  */
 function elgg_list_registered_entities($options) {
 	$defaults = array(
@@ -3778,7 +3791,7 @@ function entities_init() {
 	register_plugin_hook('unit_test', 'system', 'entities_test');
 
 	// Allow a permission override for recursive entity deletion
-	// TODO: Can this be done better?
+	// @todo Can this be done better?
 	register_plugin_hook('permissions_check','all','recursive_delete_permissions_check');
 	register_plugin_hook('permissions_check:metadata','all','recursive_delete_permissions_check');
 
diff --git a/engine/lib/extender.php b/engine/lib/extender.php
index cbcdd6eb7..7b54a7842 100644
--- a/engine/lib/extender.php
+++ b/engine/lib/extender.php
@@ -87,6 +87,7 @@ abstract class ElggExtender implements
 	 * Return the owner entity
 	 *
 	 * @return mixed
+	 * @since 1.7.0
 	 */
 	public function getOwnerEntity() {
 		return get_user($this->owner_guid);
@@ -263,7 +264,7 @@ abstract class ElggExtender implements
  * Detect the value_type for a given value.
  * Currently this is very crude.
  *
- * TODO: Make better!
+ * @todo Make better!
  *
  * @param mixed $value
  * @param string $value_type If specified, overrides the detection.
diff --git a/engine/lib/filestore.php b/engine/lib/filestore.php
index 0a30f5551..31fc9ab0d 100644
--- a/engine/lib/filestore.php
+++ b/engine/lib/filestore.php
@@ -471,7 +471,7 @@ class ElggFile extends ElggObject {
 			return $this->mimetype;
 		}
 
-		// TODO : Guess mimetype if not here
+		// @todo Guess mimetype if not here
 	}
 
 	/**
@@ -648,7 +648,8 @@ class ElggFile extends ElggObject {
 			return $this->filestore;
 		}
 
-		// If filestore meta set then retrieve filestore TODO: Better way of doing this?
+		// If filestore meta set then retrieve filestore
+		// @todo Better way of doing this?
 		$metas = get_metadata_for_entity($this->guid);
 		$parameters = array();
 		if (is_array($metas)) {
diff --git a/engine/lib/group.php b/engine/lib/group.php
index 474baf609..ab6c9112d 100644
--- a/engine/lib/group.php
+++ b/engine/lib/group.php
@@ -857,8 +857,7 @@ function group_gatekeeper($forward = true) {
  * @param string $label Used for the group edit form
  * @param boolean $default_on True if this option should be active by default
  *
- **/
-
+ */
 function add_group_tool_option($name,$label,$default_on=true) {
 	global $CONFIG;
 
diff --git a/engine/lib/install.php b/engine/lib/install.php
index e2b0c5251..42df3e17f 100644
--- a/engine/lib/install.php
+++ b/engine/lib/install.php
@@ -40,7 +40,7 @@ function validate_platform() {
 		throw new ConfigurationException(elgg_echo('ConfigurationException:BadPHPVersion'));
 	}
 
-	// TODO: Consider checking for installed modules etc
+	// @todo Consider checking for installed modules etc
 	return true;
 }
 
@@ -52,6 +52,7 @@ function validate_platform() {
  * @param string $dbname
  * @param string $host
  * @return bool
+ * @since 1.7.1
  */
 function db_check_settings($user, $password, $dbname, $host) {
 	$mysql_dblink = mysql_connect($host, $user, $password, true);
diff --git a/engine/lib/languages.php b/engine/lib/languages.php
index 98283f141..d20fa6a44 100644
--- a/engine/lib/languages.php
+++ b/engine/lib/languages.php
@@ -147,7 +147,7 @@ function register_translations($path, $load_all = false) {
  * This is only called by functions which need to know all possible translations, namely the
  * statistic gathering ones.
  *
- * TODO: Better on demand loading based on language_paths array
+ * @todo Better on demand loading based on language_paths array
  *
  * @return bool
  */
diff --git a/engine/lib/location.php b/engine/lib/location.php
index 21ee7d5fa..7b96f4a91 100644
--- a/engine/lib/location.php
+++ b/engine/lib/location.php
@@ -277,6 +277,6 @@ function list_entities_in_area($lat, $long, $radius, $type= "", $subtype = "", $
 define("MILE", 0.01515);
 define("KILOMETER", 0.00932);
 
-// TODO: get objects within x miles by entities, metadata and relationship
+// @todo get objects within x miles by entities, metadata and relationship
 
-// TODO: List
\ No newline at end of file
+// @todo List
\ No newline at end of file
diff --git a/engine/lib/mb_wrapper.php b/engine/lib/mb_wrapper.php
index 9aa4aac4c..ce70addc1 100644
--- a/engine/lib/mb_wrapper.php
+++ b/engine/lib/mb_wrapper.php
@@ -13,6 +13,7 @@ if (is_callable('mb_internal_encoding')) {
  *
  * @param str $str
  * @return array
+ * @since 1.7.0
  */
 function elgg_parse_str($str) {
 	if (is_callable('mb_parse_str')) {
@@ -64,4 +65,4 @@ foreach ($str_funcs as $func) {
 
 eval($eval_statement);
 
-// TODO: Other wrapper functions
\ No newline at end of file
+// @todo Other wrapper functions
\ No newline at end of file
diff --git a/engine/lib/memcache.php b/engine/lib/memcache.php
index ed93cacf0..1a428dac5 100644
--- a/engine/lib/memcache.php
+++ b/engine/lib/memcache.php
@@ -157,7 +157,7 @@ class ElggMemcache extends ElggSharedMemoryCache {
 		// DISABLE clearing for now - you must use delete on a specific key.
 		return true;
 
-		//TODO: Namespaces as in #532
+		// @todo Namespaces as in #532
 	}
 }
 
diff --git a/engine/lib/metadata.php b/engine/lib/metadata.php
index a07b0958d..66fa78401 100644
--- a/engine/lib/metadata.php
+++ b/engine/lib/metadata.php
@@ -572,6 +572,7 @@ function find_metadata($meta_name = "", $meta_value = "", $entity_type = "", $en
  *  metadata_owner_guids => NULL|ARR guids for metadata owners
  *
  * @return array
+ * @since 1.7.0
  */
 function elgg_get_entities_from_metadata(array $options = array()) {
 	$defaults = array(
@@ -605,6 +606,7 @@ function elgg_get_entities_from_metadata(array $options = array()) {
  * @param array $options Options
  *
  * @return array
+ * @since 1.7.0
  */
 function elgg_entities_get_metastrings_options($type, $options) {
 	$valid_types = array('metadata', 'annotation');
@@ -672,6 +674,7 @@ function elgg_entities_get_metastrings_options($type, $options) {
  * @param BOOL $case_sensitive
  * @param ARR|NULL $order_by_metadata array of names / direction
  * @return FALSE|array False on fail, array('joins', 'wheres')
+ * @since 1.7.0
  */
 function elgg_get_entity_metadata_where_sql($e_table, $n_table, $names = NULL, $values = NULL, $pairs = NULL, $pair_operator = 'AND', $case_sensitive = TRUE, $order_by_metadata = NULL, $owner_guids = NULL) {
 	global $CONFIG;
@@ -1018,6 +1021,7 @@ function list_entities_from_metadata($meta_name, $meta_value = "", $entity_type
  * @see elgg_get_entities_from_metadata
  *
  * @param array $options
+ * @since 1.7.0
  */
 function elgg_list_entities_from_metadata($options) {
 	$defaults = array(
diff --git a/engine/lib/notification.php b/engine/lib/notification.php
index 5ab9626c3..475a590ec 100644
--- a/engine/lib/notification.php
+++ b/engine/lib/notification.php
@@ -54,6 +54,7 @@ function register_notification_handler($method, $handler, $params = NULL) {
  * This function unregisters a handler for a given notification type (eg "email")
  *
  * @param string $method The method
+ * @since 1.7.1
  */
 function unregister_notification_handler($method) {
 	global $NOTIFICATION_HANDLERS;
@@ -271,6 +272,7 @@ function email_notify_handler(ElggEntity $from, ElggUser $to, $subject, $message
  * @param string $body The message body
  * @param array $params Optional parameters (none used in this function)
  * @return bool
+ * @since 1.7.2
  */
 function elgg_send_email($from, $to, $subject, $body, array $params = NULL) {
 	global $CONFIG;
diff --git a/engine/lib/objects.php b/engine/lib/objects.php
index 6023a4805..63376c72d 100644
--- a/engine/lib/objects.php
+++ b/engine/lib/objects.php
@@ -272,7 +272,7 @@ function create_object_entity($guid, $title, $description) {
  * THIS FUNCTION IS DEPRECATED.
  *
  * Delete a object's extra data.
- *
+ * @todo - this should be removed - was deprecated in 1.5 or earlier
  * @param int $guid
  */
 function delete_object_entity($guid) {
diff --git a/engine/lib/pam.php b/engine/lib/pam.php
index 590ef9fde..5dbb0e1ab 100644
--- a/engine/lib/pam.php
+++ b/engine/lib/pam.php
@@ -57,6 +57,7 @@ function register_pam_handler($handler, $importance = "sufficient", $policy = "u
  *
  * @param string $handler The PAM handler function name
  * @param string $policy - the policy type, default is "user"
+ * @since 1.7.0
  */
 function unregister_pam_handler($handler, $policy = "user") {
 	global $_PAM_HANDLERS;
diff --git a/engine/lib/plugins.php b/engine/lib/plugins.php
index 66b22a0aa..47a103dcd 100644
--- a/engine/lib/plugins.php
+++ b/engine/lib/plugins.php
@@ -622,6 +622,7 @@ function clear_plugin_setting($name, $plugin_name = "") {
  * Clear all plugin settings.
  *
  * @param string $plugin_name Optional plugin name, if not specified then it is detected from where you are calling from.
+ * @since 1.7.0
  */
 function clear_all_plugin_settings($plugin_name = "") {
 	$plugin = find_plugin_settings($plugin_name);
diff --git a/engine/lib/query.php b/engine/lib/query.php
index 619a2d288..bdb28559f 100644
--- a/engine/lib/query.php
+++ b/engine/lib/query.php
@@ -183,7 +183,7 @@
 			// Note: currently get_access_sql_suffix is hardwired to use
 			// $acl_field = "access_id", $object_owner_table = $acl_table, and
 			// $object_owner_id_field = "owner_guid"
-			// TODO: recode get_access_sql_suffix to make it possible to specify alternate field names
+			// @todo recode get_access_sql_suffix to make it possible to specify alternate field names
 			return "and ".get_access_sql_suffix($this->acl_table); // Add access controls
 
 			//return "and ({$this->acl_table}.{$this->acl_field} in {$access} or ({$this->acl_table}.{$this->acl_field} = 0 and {$this->object_owner_table}.{$this->object_owner_id_field} = {$_SESSION['id']}))";
diff --git a/engine/lib/relationships.php b/engine/lib/relationships.php
index bf55a8932..dd8a2b188 100644
--- a/engine/lib/relationships.php
+++ b/engine/lib/relationships.php
@@ -502,6 +502,7 @@ function get_entity_relationships($guid, $inverse_relationship = FALSE) {
  * 	inverse_relationship => BOOL Inverse the relationship
  *
  * @return array
+ * @since 1.7.0
  */
 function elgg_get_entities_from_relationship($options) {
 	$defaults = array(
@@ -547,6 +548,7 @@ function elgg_get_entities_from_relationship($options) {
  * @param $relationship relationship string
  * @param $entity_guid entity guid to check
  * @return mixed
+ * @since 1.7.0
  */
 function elgg_get_entity_relationship_where_sql($table, $relationship = NULL, $relationship_guid = NULL, $inverse_relationship = FALSE) {
 	if ($relationship == NULL && $entity_guid == NULL) {
diff --git a/engine/lib/river.php b/engine/lib/river.php
index 74e7322e8..09799aa59 100644
--- a/engine/lib/river.php
+++ b/engine/lib/river.php
@@ -106,6 +106,7 @@ function remove_from_river_by_object($object_guid) {
  *
  * @param int annotation_id The ID of the annotation
  * @return true|false Depending on success
+ * @since 1.7.0
  */
 function remove_from_river_by_annotation($annotation_id) {
 	// Sanitise
diff --git a/engine/lib/sessions.php b/engine/lib/sessions.php
index b74b2f524..428a521a2 100644
--- a/engine/lib/sessions.php
+++ b/engine/lib/sessions.php
@@ -186,6 +186,7 @@ function isadminloggedin() {
  *
  * @param $user_guid
  * @return bool
+ * @since 1.7.1
  */
 function elgg_is_admin_user($user_guid) {
 	global $CONFIG;
diff --git a/engine/lib/sites.php b/engine/lib/sites.php
index d67a540cc..23a922757 100644
--- a/engine/lib/sites.php
+++ b/engine/lib/sites.php
@@ -375,7 +375,7 @@ function create_site_entity($guid, $name, $description, $url) {
  * THIS FUNCTION IS DEPRECATED.
  *
  * Delete a site's extra data.
- *
+ * @todo remove
  * @param int $guid
  */
 function delete_site_entity($guid) {
diff --git a/engine/lib/tags.php b/engine/lib/tags.php
index 1d2b552ad..e73444930 100644
--- a/engine/lib/tags.php
+++ b/engine/lib/tags.php
@@ -73,7 +73,6 @@ function generate_tag_cloud(array $tags, $buckets = 6) {
  *
  * Supports similar arguments as elgg_get_entities()
  *
- * @since 1.7.1
  *
  * @param array $options Array in format:
  *
@@ -109,6 +108,7 @@ function generate_tag_cloud(array $tags, $buckets = 6) {
  *
  * @return 	false/array - if no tags or error, false
  * 			otherwise, array of objects with ->tag and ->total values
+ * @since 1.7.1
  */
 function elgg_get_tags(array $options = array()) {
 	global $CONFIG;
@@ -306,7 +306,6 @@ function get_tags($threshold = 1, $limit = 10, $metadata_name = "", $entity_type
 /**
  * Returns viewable tagcloud
  *
- * @since 1.7.1
  *
  * @see elgg_get_tags
  *
@@ -317,7 +316,7 @@ function get_tags($threshold = 1, $limit = 10, $metadata_name = "", $entity_type
  * 	subtype => must be single entity subtype
  *
  * @return string
- * 
+ * @since 1.7.1
  */
 function elgg_view_tagcloud(array $options = array()) {
 
@@ -370,10 +369,10 @@ function display_tagcloud($threshold = 1, $limit = 10, $metadata_name = "", $ent
  * This is required if you are using a non-standard metadata name
  * for your tags.
  *
- * @since 1.7
  *
  * @param string $name
- * @return TRUE
+ * @return bool
+ * @since 1.7.0
  */
 function elgg_register_tag_metadata_name($name) {
 	global $CONFIG;
@@ -392,9 +391,8 @@ function elgg_register_tag_metadata_name($name) {
 /**
  * Returns an array of valid metadata names for tags.
  *
- * @since 1.7
- *
  * @return array
+ * @since 1.7.0
  */
 function elgg_get_registered_tag_metadata_names() {
 	global $CONFIG;
diff --git a/engine/lib/users.php b/engine/lib/users.php
index 99ef15246..3722c8ed1 100644
--- a/engine/lib/users.php
+++ b/engine/lib/users.php
@@ -682,7 +682,7 @@ function remove_user_admin($user_guid) {
  * THIS FUNCTION IS DEPRECATED.
  *
  * Delete a user's extra data.
- *
+ * @todo remove
  * @param int $guid
  */
 function delete_user_entity($guid) {
@@ -1362,7 +1362,7 @@ function request_user_validation($user_guid) {
  * @return bool
  */
 function is_email_address($address) {
-	// TODO: Make this better!
+	// @todo Make this better!
 
 	if (strpos($address, '@')=== false) {
 		return false;
@@ -1434,7 +1434,8 @@ function validate_username($username) {
 		throw new RegistrationException(elgg_echo('registration:invalidchars'));
 	}
 
-	// Belts and braces TODO: Tidy into main unicode
+	// Belts and braces
+	// @todo Tidy into main unicode
 	$blacklist2 = '\'/\\"*& ?#%^(){}[]~?<>;|¬`@-+=';
 	for ($n=0; $n < strlen($blacklist2); $n++) {
 		if (strpos($username, $blacklist2[$n])!==false) {
@@ -1718,7 +1719,7 @@ function set_last_login($user_guid) {
  * A permissions plugin hook that grants access to users if they are newly created - allows
  * for email activation.
  *
- * TODO: Do this in a better way!
+ * @todo Do this in a better way!
  *
  * @param unknown_type $hook
  * @param unknown_type $entity_type
@@ -1839,7 +1840,7 @@ function users_init() {
 	register_elgg_event_handler('create', 'user', 'user_create_hook_add_site_relationship');
 
 	// Handle a special case for newly created users when the user is not logged in
-	// TODO: handle this better!
+	// @todo handle this better!
 	register_plugin_hook('permissions_check','all','new_user_enable_permissions_check');
 }
 
diff --git a/engine/lib/views.php b/engine/lib/views.php
index 76d2a57da..ceaced80c 100644
--- a/engine/lib/views.php
+++ b/engine/lib/views.php
@@ -451,7 +451,7 @@ function elgg_view_disable_simplecache() {
  * @param string $dir
  * @param string $base
  * @return array
- * @since 1.7
+ * @since 1.7.0
  */
 function elgg_get_views($dir, $base) {
 	$return = array();
@@ -886,6 +886,7 @@ function set_template_handler($function_name) {
  * @param string $view_extension This view is added to $view
  * @param int $priority The priority, from 0 to 1000, to add at (lowest numbers displayed first)
  * @param string $viewtype Not used
+ * @since 1.7.0
  */
 function elgg_extend_view($view, $view_extension, $priority = 501, $viewtype = '') {
 	global $CONFIG;
@@ -990,6 +991,7 @@ function set_view_location($view, $location, $viewtype = '') {
  * @param string $folder The folder to begin looking in
  * @param string $base_location_path The base views directory to use with set_view_location
  * @param string $viewtype The type of view we're looking at (default, rss, etc)
+ * @since 1.7.0
  */
 function autoregister_views($view_base, $folder, $base_location_path, $viewtype) {
 	if (!isset($i)) {
@@ -1071,6 +1073,7 @@ function page_draw($title, $body, $page_shell = 'page_shells/default', $vars = a
  *
  * @param string $view_type
  * @return bool
+ * @since 1.7.2
  */
 function elgg_is_valid_view_type($view_type) {
 	global $CONFIG;
diff --git a/engine/lib/widgets.php b/engine/lib/widgets.php
index 1862ef7e4..03524da62 100644
--- a/engine/lib/widgets.php
+++ b/engine/lib/widgets.php
@@ -284,6 +284,7 @@ function add_widget_type($handler, $name, $description, $context = "all", $multi
  * Remove a widget type
  *
  * @param string $handler The identifier for the widget handler
+ * @since 1.7.1
  */
 function remove_widget_type($handler) {
 	global $CONFIG;
@@ -378,7 +379,7 @@ function save_widget_info($widget_guid, $params) {
 					'guid','owner_guid','site_guid'
 				))) {
 					if (is_array($value)) {
-						// TODO: Handle arrays securely
+						// @todo Handle arrays securely
 						$widget->setMetaData($name, $value, "", true);
 					} else {
 						$widget->$name = $value;
diff --git a/engine/lib/xml-rpc.php b/engine/lib/xml-rpc.php
index 7c369edc1..110dd76dd 100644
--- a/engine/lib/xml-rpc.php
+++ b/engine/lib/xml-rpc.php
@@ -458,7 +458,7 @@
 	        case 'value':
 	            return xmlrpc_scalar_value($object->children[0]);
 	        default:
-	            // TODO unsupported, throw an error
+	            // @todo unsupported, throw an error
 	            return false;
 	    }
 	}