Doc fixes and inline type hints for variables (big static analysis cleanup)

51 files changed, 229 insertions, 115 deletions

diff --git a/engine/classes/ElggAnnotation.php b/engine/classes/ElggAnnotation.php
index 511b5151f..175e7049d 100644
--- a/engine/classes/ElggAnnotation.php
+++ b/engine/classes/ElggAnnotation.php
@@ -11,6 +11,9 @@
  * @package    Elgg.Core
  * @subpackage DataModel.Annotations
  * @link       http://docs.elgg.org/DataModel/Annotations
+ *
+ * @property string $value_type
+ * @property string $enabled
  */
 class ElggAnnotation extends ElggExtender {
 
@@ -56,6 +59,8 @@ class ElggAnnotation extends ElggExtender {
 	 * Save this instance
 	 *
 	 * @return int an object id
+	 *
+	 * @throws IOException
 	 */
 	function save() {
 		if ($this->id > 0) {
diff --git a/engine/classes/ElggAutoP.php b/engine/classes/ElggAutoP.php
index 89d77e583..40600aa13 100644
--- a/engine/classes/ElggAutoP.php
+++ b/engine/classes/ElggAutoP.php
@@ -117,6 +117,8 @@ class ElggAutoP {
 		// serialize back to HTML
 		$html = $this->_doc->saveHTML();
 
+		// Note: we create <autop> elements, which will later be converted to paragraphs
+
 		// split AUTOPs into multiples at /\n\n+/
 		$html = preg_replace('/(' . $this->_unique . 'NL){2,}/', '</autop><autop>', $html);
 		$html = str_replace(array($this->_unique . 'BR', $this->_unique . 'NL', '<br>'), 
@@ -134,6 +136,7 @@ class ElggAutoP {
 
 		// strip AUTOPs that only have comments/whitespace
 		foreach ($this->_xpath->query('//autop') as $autop) {
+			/* @var DOMElement $autop */
 			$hasContent = false;
 			if (trim($autop->textContent) !== '') {
 				$hasContent = true;
@@ -146,13 +149,14 @@ class ElggAutoP {
 				}
 			}
 			if (!$hasContent) {
-				// strip w/ preg_replace later (faster than moving nodes out)
+				// mark to be later replaced w/ preg_replace (faster than moving nodes out)
 				$autop->setAttribute("r", "1");
 			}
 		}
 
-		// remove a single AUTOP inside certain elements
+		// If a DIV contains a single AUTOP, remove it
 		foreach ($this->_xpath->query('//div') as $el) {
+			/* @var DOMElement $el */
 			$autops = $this->_xpath->query('./autop', $el);
 			if ($autops->length === 1) {
 				// strip w/ preg_replace later (faster than moving nodes out)
@@ -185,7 +189,7 @@ class ElggAutoP {
 	 * @param DOMElement $el
 	 */
 	protected function _addParagraphs(DOMElement $el) {
-		// no need to recurse, just queue up
+		// no need to call recursively, just queue up
 		$elsToProcess = array($el);
 		$inlinesToProcess = array();
 		while ($el = array_shift($elsToProcess)) {
diff --git a/engine/classes/ElggData.php b/engine/classes/ElggData.php
index 3470ee1cf..a0df3c924 100644
--- a/engine/classes/ElggData.php
+++ b/engine/classes/ElggData.php
@@ -5,6 +5,9 @@
  *
  * @package    Elgg.Core
  * @subpackage DataModel
+ *
+ * @property int $owner_guid
+ * @property int $time_created
  */
 abstract class ElggData implements
 	Loggable,	// Can events related to this object class be logged
@@ -33,14 +36,12 @@ abstract class ElggData implements
 	 *                        Passing false returns false.  Core constructors always pass false.
 	 *                        Does nothing either way since attributes are initialized by the time
 	 *                        this is called.
-	 * @return false|void False is
+	 * @return void
 	 * @deprecated 1.8 Use initializeAttributes()
 	 */
 	protected function initialise_attributes($pre18_api = true) {
 		if ($pre18_api) {
 			elgg_deprecated_notice('initialise_attributes() is deprecated by initializeAttributes()', 1.8);
-		} else {
-			return false;
 		}
 	}
 
@@ -111,7 +112,7 @@ abstract class ElggData implements
 	 * @param string $name  The attribute to set
 	 * @param mixed  $value The value to set it to
 	 *
-	 * @return The success of your set funtion?
+	 * @return bool The success of your set function?
 	 */
 	abstract protected function set($name, $value);
 
@@ -195,7 +196,7 @@ abstract class ElggData implements
 	 *
 	 * @see Iterator::current()
 	 *
-	 * @return void
+	 * @return mixed
 	 */
 	public function current() {
 		return current($this->attributes);
@@ -206,7 +207,7 @@ abstract class ElggData implements
 	 *
 	 * @see Iterator::key()
 	 *
-	 * @return void
+	 * @return string
 	 */
 	public function key() {
 		return key($this->attributes);
@@ -228,7 +229,7 @@ abstract class ElggData implements
 	 *
 	 * @see Iterator::valid()
 	 *
-	 * @return void
+	 * @return bool
 	 */
 	public function valid() {
 		return $this->valid;
@@ -266,7 +267,7 @@ abstract class ElggData implements
 	 *
 	 * @param mixed $key Name
 	 *
-	 * @return void
+	 * @return mixed
 	 */
 	public function offsetGet($key) {
 		if (array_key_exists($key, $this->attributes)) {
diff --git a/engine/classes/ElggDiskFilestore.php b/engine/classes/ElggDiskFilestore.php
index 7aace43ba..5483eed81 100644
--- a/engine/classes/ElggDiskFilestore.php
+++ b/engine/classes/ElggDiskFilestore.php
@@ -108,7 +108,7 @@ class ElggDiskFilestore extends ElggFilestore {
 	 *
 	 * @param resource $f      File pointer resource
 	 * @param int      $length The number of bytes to read
-	 * @param inf      $offset The number of bytes to start after
+	 * @param int      $offset The number of bytes to start after
 	 *
 	 * @return mixed Contents of file or false on fail.
 	 */
@@ -198,6 +198,7 @@ class ElggDiskFilestore extends ElggFilestore {
 	 * @param ElggFile $file File object
 	 *
 	 * @return string The full path of where the file is stored
+	 * @throws InvalidParameterException
 	 */
 	public function getFilenameOnFilestore(ElggFile $file) {
 		$owner_guid = $file->getOwnerGuid();
@@ -324,7 +325,7 @@ class ElggDiskFilestore extends ElggFilestore {
 	 *
 	 * @param int $identifier The guide of the entity to store the data under.
 	 *
-	 * @return str The path where the entity's data will be stored.
+	 * @return string The path where the entity's data will be stored.
 	 * @deprecated 1.8 Use ElggDiskFilestore::makeFileMatrix()
 	 */
 	protected function make_file_matrix($identifier) {
@@ -338,7 +339,7 @@ class ElggDiskFilestore extends ElggFilestore {
 	 *
 	 * @param int $guid The guide of the entity to store the data under.
 	 *
-	 * @return str The path where the entity's data will be stored.
+	 * @return string The path where the entity's data will be stored.
 	 */
 	protected function makeFileMatrix($guid) {
 		$entity = get_entity($guid);
@@ -363,7 +364,7 @@ class ElggDiskFilestore extends ElggFilestore {
 	 *
 	 * @param int $guid The entity to contrust a matrix for
 	 *
-	 * @return str The
+	 * @return string The
 	 */
 	protected function user_file_matrix($guid) {
 		elgg_deprecated_notice('ElggDiskFilestore::user_file_matrix() is deprecated by ::makeFileMatrix()', 1.8);
diff --git a/engine/classes/ElggEntity.php b/engine/classes/ElggEntity.php
index 929abceb2..0cb8e5f7c 100644
--- a/engine/classes/ElggEntity.php
+++ b/engine/classes/ElggEntity.php
@@ -34,6 +34,7 @@
  * @property int    $access_id      Specifies the visibility level of this entity
  * @property int    $time_created   A UNIX timestamp of when the entity was created (read-only, set on first save)
  * @property int    $time_updated   A UNIX timestamp of when the entity was last updated (automatically updated on save)
+ * @property-read string $enabled
  */
 abstract class ElggEntity extends ElggData implements
 	Notable,    // Calendar interface
@@ -940,7 +941,7 @@ abstract class ElggEntity extends ElggData implements
 	 * @param ElggMetadata $metadata  The piece of metadata to specifically check
 	 * @param int          $user_guid The user GUID, optionally (default: logged in user)
 	 *
-	 * @return true|false
+	 * @return bool
 	 */
 	function canEditMetadata($metadata = null, $user_guid = 0) {
 		return can_edit_entity_metadata($this->getGUID(), $user_guid, $metadata);
@@ -1668,9 +1669,11 @@ abstract class ElggEntity extends ElggData implements
 	/**
 	 * Import data from an parsed ODD xml data array.
 	 *
-	 * @param array $data XML data
+	 * @param ODD $data XML data
 	 *
 	 * @return true
+	 *
+	 * @throws InvalidParameterException
 	 */
 	public function import(ODD $data) {
 		if (!($data instanceof ODDEntity)) {
diff --git a/engine/classes/ElggFile.php b/engine/classes/ElggFile.php
index f21621ffd..86406d108 100644
--- a/engine/classes/ElggFile.php
+++ b/engine/classes/ElggFile.php
@@ -178,6 +178,8 @@ class ElggFile extends ElggObject {
 	 * @param string $mode Either read/write/append
 	 *
 	 * @return resource File handler
+	 *
+	 * @throws IOException|InvalidParameterException
 	 */
 	public function open($mode) {
 		if (!$this->getFilename()) {
@@ -347,6 +349,8 @@ class ElggFile extends ElggObject {
 	 * a filestore as recorded in metadata or the system default.
 	 *
 	 * @return ElggFilestore
+	 *
+	 * @throws ClassNotFoundException
 	 */
 	protected function getFilestore() {
 		// Short circuit if already set.
diff --git a/engine/classes/ElggFileCache.php b/engine/classes/ElggFileCache.php
index 34178d452..e654f1db2 100644
--- a/engine/classes/ElggFileCache.php
+++ b/engine/classes/ElggFileCache.php
@@ -13,6 +13,8 @@ class ElggFileCache extends ElggCache {
 	 * @param string $cache_path The cache path.
 	 * @param int    $max_age    Maximum age in seconds, 0 if no limit.
 	 * @param int    $max_size   Maximum size of cache in seconds, 0 if no limit.
+	 *
+	 * @throws ConfigurationException
 	 */
 	function __construct($cache_path, $max_age = 0, $max_size = 0) {
 		$this->setVariable("cache_path", $cache_path);
diff --git a/engine/classes/ElggGroup.php b/engine/classes/ElggGroup.php
index ea257f368..d17fa4f1a 100644
--- a/engine/classes/ElggGroup.php
+++ b/engine/classes/ElggGroup.php
@@ -32,7 +32,7 @@ class ElggGroup extends ElggEntity
 	 * @param mixed $guid If an int, load that GUID.
 	 * 	If an entity table db row, then will load the rest of the data.
 	 *
-	 * @throws Exception if there was a problem creating the group.
+	 * @throws IOException|InvalidParameterException if there was a problem creating the group.
 	 */
 	function __construct($guid = null) {
 		$this->initializeAttributes();
diff --git a/engine/classes/ElggMemcache.php b/engine/classes/ElggMemcache.php
index d9539b9cb..91d50ab89 100644
--- a/engine/classes/ElggMemcache.php
+++ b/engine/classes/ElggMemcache.php
@@ -32,6 +32,8 @@ class ElggMemcache extends ElggSharedMemoryCache {
 	 *
 	 * @param string $namespace The namespace for this cache to write to -
 	 * note, namespaces of the same name are shared!
+	 *
+	 * @throws ConfigurationException
 	 */
 	function __construct($namespace = 'default') {
 		global $CONFIG;
diff --git a/engine/classes/ElggMenuBuilder.php b/engine/classes/ElggMenuBuilder.php
index d7f85685c..2fd5ad9c4 100644
--- a/engine/classes/ElggMenuBuilder.php
+++ b/engine/classes/ElggMenuBuilder.php
@@ -8,6 +8,9 @@
  */
 class ElggMenuBuilder {
 
+	/**
+	 * @var ElggMenuItem[]
+	 */
 	protected $menu = array();
 
 	protected $selected = null;
@@ -15,7 +18,7 @@ class ElggMenuBuilder {
 	/**
 	 * ElggMenuBuilder constructor
 	 *
-	 * @param array $menu Array of ElggMenuItem objects
+	 * @param ElggMenuItem[] $menu Array of ElggMenuItem objects
 	 */
 	public function __construct(array $menu) {
 		$this->menu = $menu;
@@ -107,6 +110,7 @@ class ElggMenuBuilder {
 			$children = array();
 			// divide base nodes from children
 			foreach ($section as $menu_item) {
+				/* @var ElggMenuItem $menu_item */
 				$parent_name = $menu_item->getParentName();
 				if (!$parent_name) {
 					$parents[$menu_item->getName()] = $menu_item;
@@ -216,6 +220,7 @@ class ElggMenuBuilder {
 				array_push($stack, $root);
 				while (!empty($stack)) {
 					$node = array_pop($stack);
+					/* @var ElggMenuItem $node */
 					$node->sortChildren($sort_callback);
 					$children = $node->getChildren();
 					if ($children) {
diff --git a/engine/classes/ElggMetadata.php b/engine/classes/ElggMetadata.php
index 7f45dc3ea..3a8e2d817 100644
--- a/engine/classes/ElggMetadata.php
+++ b/engine/classes/ElggMetadata.php
@@ -6,6 +6,10 @@
  *
  * @package    Elgg.Core
  * @subpackage Metadata
+ *
+ * @property string $value_type
+ * @property int $owner_guid
+ * @property string $enabled
  */
 class ElggMetadata extends ElggExtender {
 
diff --git a/engine/classes/ElggPlugin.php b/engine/classes/ElggPlugin.php
index 8f71b79a8..066fd9a79 100644
--- a/engine/classes/ElggPlugin.php
+++ b/engine/classes/ElggPlugin.php
@@ -145,7 +145,7 @@ class ElggPlugin extends ElggObject {
 	/**
 	 * Sets the location of this plugin.
 	 *
-	 * @param path $id The path to the plugin's dir.
+	 * @param string $id The path to the plugin's dir.
 	 * @return bool
 	 */
 	public function setID($id) {
diff --git a/engine/classes/ElggPluginPackage.php b/engine/classes/ElggPluginPackage.php
index 2dc4bdb3d..209242288 100644
--- a/engine/classes/ElggPluginPackage.php
+++ b/engine/classes/ElggPluginPackage.php
@@ -100,7 +100,6 @@ class ElggPluginPackage {
 	 * @param string $plugin   The ID (directory name) or full path of the plugin.
 	 * @param bool   $validate Automatically run isValid()?
 	 *
-	 * @return true
 	 * @throws PluginException
 	 */
 	public function __construct($plugin, $validate = true) {
@@ -213,6 +212,7 @@ class ElggPluginPackage {
 			return false;
 		}
 
+		// Note: $conflicts and $requires are not unused. They're called dynamically
 		$conflicts = $this->getManifest()->getConflicts();
 		$requires = $this->getManifest()->getRequires();
 		$provides = $this->getManifest()->getProvides();
@@ -330,8 +330,10 @@ class ElggPluginPackage {
 	 * @return bool|array
 	 */
 	public function checkDependencies($full_report = false) {
+		// Note: $conflicts and $requires are not unused. They're called dynamically
 		$requires = $this->getManifest()->getRequires();
 		$conflicts = $this->getManifest()->getConflicts();
+
 		$enabled_plugins = elgg_get_plugins('active');
 		$this_id = $this->getID();
 		$report = array();
@@ -368,6 +370,7 @@ class ElggPluginPackage {
 		$check_types = array('requires', 'conflicts');
 
 		if ($full_report) {
+			// Note: $suggests is not unused. It's called dynamically
 			$suggests = $this->getManifest()->getSuggests();
 			$check_types[] = 'suggests';
 		}
diff --git a/engine/classes/ElggRelationship.php b/engine/classes/ElggRelationship.php
index efc0f7eff..377a41093 100644
--- a/engine/classes/ElggRelationship.php
+++ b/engine/classes/ElggRelationship.php
@@ -71,6 +71,7 @@ class ElggRelationship extends ElggData implements
 	 * Save the relationship
 	 *
 	 * @return int the relationship id
+	 * @throws IOException
 	 */
 	public function save() {
 		if ($this->id > 0) {
@@ -145,7 +146,7 @@ class ElggRelationship extends ElggData implements
 	 * @param ODD $data ODD data
 
 	 * @return bool
-	 * @throws ImportException
+	 * @throws ImportException|InvalidParameterException
 	 */
 	public function import(ODD $data) {
 		if (!($data instanceof ODDRelationship)) {
diff --git a/engine/classes/ElggWidget.php b/engine/classes/ElggWidget.php
index 99708f66a..c123e5032 100644
--- a/engine/classes/ElggWidget.php
+++ b/engine/classes/ElggWidget.php
@@ -7,6 +7,11 @@
  *
  * @package    Elgg.Core
  * @subpackage Widgets
+ *
+ * @property-read string $handler internal, do not use
+ * @property-read string $column internal, do not use
+ * @property-read string $order internal, do not use
+ * @property-read string $context internal, do not use
  */
 class ElggWidget extends ElggObject {
 
diff --git a/engine/classes/ElggXMLElement.php b/engine/classes/ElggXMLElement.php
index 65a13912c..4e4b7e63c 100644
--- a/engine/classes/ElggXMLElement.php
+++ b/engine/classes/ElggXMLElement.php
@@ -32,7 +32,7 @@ class ElggXMLElement {
 	}
 
 	/**
-	 * @return array:string The attributes
+	 * @return string[] The attributes
 	 */
 	public function getAttributes() {
 		//include namespace declarations as attributes
@@ -64,7 +64,7 @@ class ElggXMLElement {
 	}
 
 	/**
-	 * @return array:ElggXMLElement Child elements
+	 * @return ElggXMLElement[] Child elements
 	 */
 	public function getChildren() {
 		$children = $this->_element->children();
diff --git a/engine/classes/ODDMetaData.php b/engine/classes/ODDMetaData.php
index 58862e0fb..09b653582 100644
--- a/engine/classes/ODDMetaData.php
+++ b/engine/classes/ODDMetaData.php
@@ -10,12 +10,12 @@ class ODDMetaData extends ODD {
 	/**
 	 * New ODD metadata
 	 *
-	 * @param unknown_type $uuid        Unique ID
-	 * @param unknown_type $entity_uuid Another unique ID
-	 * @param unknown_type $name        Name
-	 * @param unknown_type $value       Value
-	 * @param unknown_type $type        Type
-	 * @param unknown_type $owner_uuid  Owner ID
+	 * @param string $uuid        Unique ID
+	 * @param string $entity_uuid Another unique ID
+	 * @param string $name        Name
+	 * @param string $value       Value
+	 * @param string $type        Type
+	 * @param string $owner_uuid  Owner ID
 	 */
 	function __construct($uuid, $entity_uuid, $name, $value, $type = "", $owner_uuid = "") {
 		parent::__construct();
@@ -31,7 +31,7 @@ class ODDMetaData extends ODD {
 	/**
 	 * Returns 'metadata'
 	 *
-	 * @return 'metadata'
+	 * @return string 'metadata'
 	 */
 	protected function getTagName() {
 		return "metadata";
diff --git a/engine/classes/ODDRelationship.php b/engine/classes/ODDRelationship.php
index 2906b1c73..8b1fe217b 100644
--- a/engine/classes/ODDRelationship.php
+++ b/engine/classes/ODDRelationship.php
@@ -10,9 +10,9 @@ class ODDRelationship extends ODD {
 	/**
 	 * New ODD Relationship
 	 *
-	 * @param unknown_type $uuid1 First UUID
-	 * @param unknown_type $type  Type of telationship
-	 * @param unknown_type $uuid2 Second UUId
+	 * @param string $uuid1 First UUID
+	 * @param string $type  Type of telationship
+	 * @param string $uuid2 Second UUId
 	 */
 	function __construct($uuid1, $type, $uuid2) {
 		parent::__construct();
@@ -25,7 +25,7 @@ class ODDRelationship extends ODD {
 	/**
 	 * Returns 'relationship'
 	 *
-	 * @return 'relationship'
+	 * @return string 'relationship'
 	 */
 	protected function getTagName() {
 		return "relationship";
diff --git a/engine/lib/access.php b/engine/lib/access.php
index f7d3bf7ea..de0693ea8 100644
--- a/engine/lib/access.php
+++ b/engine/lib/access.php
@@ -1015,6 +1015,10 @@ function access_init() {
  *
  * Returns true to override the access system or null if no change is needed.
  *
+ * @param string $hook
+ * @param string $type
+ * @param bool $value
+ * @param array $params
  * @return true|null
  * @access private
  */
@@ -1047,6 +1051,13 @@ function elgg_override_permissions($hook, $type, $value, $params) {
 
 /**
  * Runs unit tests for the entities object.
+ *
+ * @param string $hook
+ * @param string $type
+ * @param array $value
+ * @param array $params
+ * @return array
+ *
  * @access private
  */
 function access_test($hook, $type, $value, $params) {
diff --git a/engine/lib/admin.php b/engine/lib/admin.php
index 35ab5599d..3677a3b69 100644
--- a/engine/lib/admin.php
+++ b/engine/lib/admin.php
@@ -380,6 +380,7 @@ function elgg_admin_add_plugin_settings_menu() {
  */
 function elgg_admin_sort_page_menu($hook, $type, $return, $params) {
 	$configure_items = $return['configure'];
+	/* @var ElggMenuItem[] $configure_items */
 	foreach ($configure_items as $menu_item) {
 		if ($menu_item->getName() == 'settings') {
 			$settings = $menu_item;
@@ -387,6 +388,7 @@ function elgg_admin_sort_page_menu($hook, $type, $return, $params) {
 	}
 
 	// keep the basic and advanced settings at the top
+	/* @var ElggMenuItem $settings */
 	$children = $settings->getChildren();
 	$site_settings = array_splice($children, 0, 2);
 	usort($children, array('ElggMenuBuilder', 'compareByText'));
@@ -552,7 +554,7 @@ function admin_plugin_screenshot_page_handler($pages) {
  *	* COPYRIGHT.txt
  *	* LICENSE.txt
  *
- * @param type $page
+ * @param array $pages
  * @return bool
  * @access private
  */
@@ -615,7 +617,11 @@ function admin_markdown_page_handler($pages) {
 /**
  * Adds default admin widgets to the admin dashboard.
  *
- * @return void
+ * @param string $event
+ * @param string $type
+ * @param ElggUser $user
+ *
+ * @return null|true
  * @access private
  */
 function elgg_add_admin_widgets($event, $type, $user) {
@@ -637,6 +643,7 @@ function elgg_add_admin_widgets($event, $type, $user) {
 			$guid = elgg_create_widget($user->getGUID(), $handler, 'admin');
 			if ($guid) {
 				$widget = get_entity($guid);
+				/* @var ElggWidget $widget */
 				$widget->move($column, $position);
 			}
 		}
diff --git a/engine/lib/annotations.php b/engine/lib/annotations.php
index 3b9f84703..9ba0491b2 100644
--- a/engine/lib/annotations.php
+++ b/engine/lib/annotations.php
@@ -30,7 +30,7 @@ function row_to_elggannotation($row) {
  *
  * @param int $id The id of the annotation object being retrieved.
  *
- * @return false|ElggAnnotation
+ * @return ElggAnnotation|false
  */
 function elgg_get_annotation_from_id($id) {
 	return elgg_get_metastring_based_object_from_id($id, 'annotations');
@@ -195,7 +195,7 @@ function update_annotation($annotation_id, $name, $value, $value_type, $owner_gu
  *                                   for the proper use of the "calculation" option.
  *
  *
- * @return mixed
+ * @return ElggAnnotation[]|mixed
  * @since 1.8.0
  */
 function elgg_get_annotations(array $options = array()) {
@@ -451,6 +451,7 @@ function elgg_list_entities_from_annotation_calculation($options) {
  * @elgg_plugin_hook export all
  *
  * @return mixed
+ * @throws InvalidParameterException
  * @access private
  */
 function export_annotation_plugin_hook($hook, $entity_type, $returnvalue, $params) {
@@ -557,6 +558,12 @@ function elgg_register_annotation_url_handler($extender_name = "all", $function_
 
 /**
  * Register annotation unit tests
+ *
+ * @param string $hook
+ * @param string $type
+ * @param array $value
+ * @param array $params
+ * @return array
  * @access private
  */
 function annotations_test($hook, $type, $value, $params) {
diff --git a/engine/lib/cache.php b/engine/lib/cache.php
index be1c43e14..5c917bb18 100644
--- a/engine/lib/cache.php
+++ b/engine/lib/cache.php
@@ -222,7 +222,7 @@ function elgg_get_simplecache_url($type, $view) {
 /**
  * Regenerates the simple cache.
  *
- * @warning This does not invalidate the cache, but actively resets it.
+ * @warning This does not invalidate the cache, but actively rebuilds it.
  *
  * @param string $viewtype Optional viewtype to regenerate. Defaults to all valid viewtypes.
  *
diff --git a/engine/lib/configuration.php b/engine/lib/configuration.php
index 385021581..851430127 100644
--- a/engine/lib/configuration.php
+++ b/engine/lib/configuration.php
@@ -36,6 +36,7 @@ function elgg_get_site_url($site_guid = 0) {
 	if (!$site instanceof ElggSite) {
 		return false;
 	}
+	/* @var ElggSite $site */
 
 	return $site->url;
 }
@@ -173,7 +174,7 @@ function elgg_save_config($name, $value, $site_guid = 0) {
 /**
  * Check that installation has completed and the database is populated.
  *
- * @throws InstallationException
+ * @throws InstallationException|DatabaseException
  * @return void
  * @access private
  */
@@ -407,7 +408,7 @@ function unset_config($name, $site_guid = 0) {
  * @param string $value     Its value
  * @param int    $site_guid Optionally, the GUID of the site (current site is assumed by default)
  *
- * @return 0
+ * @return bool
  * @todo The config table doens't have numeric primary keys so insert_data returns 0.
  * @todo Use "INSERT ... ON DUPLICATE KEY UPDATE" instead of trying to delete then add.
  * @see unset_config()
diff --git a/engine/lib/cron.php b/engine/lib/cron.php
index f7a032f4a..f2939bdd6 100644
--- a/engine/lib/cron.php
+++ b/engine/lib/cron.php
@@ -26,6 +26,7 @@ function cron_init() {
  * @param array $page Pages
  *
  * @return bool
+ * @throws CronException
  * @access private
  */
 function cron_page_handler($page) {
diff --git a/engine/lib/database.php b/engine/lib/database.php
index 7d90b30b8..18c30cb8e 100644
--- a/engine/lib/database.php
+++ b/engine/lib/database.php
@@ -17,7 +17,9 @@
  * $DB_QUERY_CACHE[$query] => array(result1, result2, ... resultN)
  * </code>
  *
- * @global array $DB_QUERY_CACHE
+ * @warning be array this var may be an array or ElggStaticVariableCache depending on when called :(
+ *
+ * @global ElggStaticVariableCache|array $DB_QUERY_CACHE
  */
 global $DB_QUERY_CACHE;
 $DB_QUERY_CACHE = array();
@@ -48,7 +50,7 @@ $DB_DELAYED_QUERIES = array();
  * Each database link created with establish_db_link($name) is stored in
  * $dblink as $dblink[$name] => resource.  Use get_db_link($name) to retrieve it.
  *
- * @global array $dblink
+ * @global resource[] $dblink
  */
 global $dblink;
 $dblink = array();
@@ -72,6 +74,7 @@ $dbcalls = 0;
  * resource. eg "read", "write", or "readwrite".
  *
  * @return void
+ * @throws DatabaseException
  * @access private
  */
 function establish_db_link($dblinkname = "readwrite") {
@@ -197,7 +200,7 @@ function db_delayedexecution_shutdown_hook() {
  *
  * @param string $dblinktype The type of link we want: "read", "write" or "readwrite".
  *
- * @return object Database link
+ * @return resource Database link
  * @access private
  */
 function get_db_link($dblinktype) {
@@ -216,7 +219,7 @@ function get_db_link($dblinktype) {
 /**
  * Execute an EXPLAIN for $query.
  *
- * @param str   $query The query to explain
+ * @param string $query The query to explain
  * @param mixed $link  The database link resource to user.
  *
  * @return mixed An object of the query's result, or FALSE
@@ -240,9 +243,9 @@ function explain_query($query, $link) {
  * {@link $dbcalls} is incremented and the query is saved into the {@link $DB_QUERY_CACHE}.
  *
  * @param string $query  The query
- * @param link   $dblink The DB link
+ * @param resource   $dblink The DB link
  *
- * @return The result of mysql_query()
+ * @return resource result of mysql_query()
  * @throws DatabaseException
  * @access private
  */
@@ -275,7 +278,7 @@ function execute_query($query, $dblink) {
  * the raw result from {@link mysql_query()}.
  *
  * @param string   $query   The query to execute
- * @param resource $dblink  The database link to use or the link type (read | write)
+ * @param resource|string $dblink  The database link to use or the link type (read | write)
  * @param string   $handler A callback function to pass the results array to
  *
  * @return true
@@ -410,7 +413,7 @@ function elgg_query_runner($query, $callback = null, $single = false) {
 
 		// test for callback once instead of on each iteration.
 		// @todo check profiling to see if this needs to be broken out into
-		// explicit cases instead of checking in the interation.
+		// explicit cases instead of checking in the iteration.
 		$is_callable = is_callable($callback);
 		while ($row = mysql_fetch_object($result)) {
 			if ($is_callable) {
@@ -459,6 +462,7 @@ function insert_data($query) {
 
 	// Invalidate query cache
 	if ($DB_QUERY_CACHE) {
+		/* @var ElggStaticVariableCache $DB_QUERY_CACHE */
 		$DB_QUERY_CACHE->clear();
 	}
 
@@ -490,6 +494,7 @@ function update_data($query) {
 
 	// Invalidate query cache
 	if ($DB_QUERY_CACHE) {
+		/* @var ElggStaticVariableCache $DB_QUERY_CACHE */
 		$DB_QUERY_CACHE->clear();
 		elgg_log("Query cache invalidated", 'NOTICE');
 	}
@@ -520,6 +525,7 @@ function delete_data($query) {
 
 	// Invalidate query cache
 	if ($DB_QUERY_CACHE) {
+		/* @var ElggStaticVariableCache $DB_QUERY_CACHE */
 		$DB_QUERY_CACHE->clear();
 		elgg_log("Query cache invalidated", 'NOTICE');
 	}
diff --git a/engine/lib/elgglib.php b/engine/lib/elgglib.php
index 540605876..746fd8aa9 100644
--- a/engine/lib/elgglib.php
+++ b/engine/lib/elgglib.php
@@ -124,7 +124,8 @@ function elgg_load_library($name) {
  * @param string $location URL to forward to browser to. Can be path relative to the network's URL.
  * @param string $reason   Short explanation for why we're forwarding
  *
- * @return False False if headers have been sent. Terminates execution if forwarding.
+ * @return false False if headers have been sent. Terminates execution if forwarding.
+ * @throws SecurityException
  */
 function forward($location = "", $reason = 'system') {
 	global $CONFIG;
@@ -528,7 +529,7 @@ function sanitise_filepath($path, $append_slash = TRUE) {
  * @param string $register Types of message: "error", "success" (default: success)
  * @param bool   $count    Count the number of messages (default: false)
  *
- * @return true|false|array Either the array of messages, or a response regarding
+ * @return bool|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.
  */
@@ -839,7 +840,7 @@ function elgg_trigger_event($event, $object_type, $object = null) {
  *
  * @param string   $hook     The name of the hook
  * @param string   $type     The type of the hook
- * @param callback $callback The name of a valid function or an array with object and method
+ * @param callable $callback The name of a valid function or an array with object and method
  * @param int      $priority The priority - 500 is default, lower numbers called first
  *
  * @return bool
@@ -885,7 +886,7 @@ function elgg_register_plugin_hook_handler($hook, $type, $callback, $priority =
  *
  * @param string   $hook        The name of the hook
  * @param string   $entity_type The name of the type of entity (eg "user", "object" etc)
- * @param callback $callback    The PHP callback to be removed
+ * @param callable $callback    The PHP callback to be removed
  *
  * @return void
  * @since 1.8.0
@@ -1060,6 +1061,7 @@ function _elgg_php_exception_handler($exception) {
  * @param array  $vars     An array that points to the active symbol table where error occurred
  *
  * @return true
+ * @throws Exception
  * @access private
  * @todo Replace error_log calls with elgg_log calls.
  */
@@ -1354,7 +1356,7 @@ function full_url() {
  * @param array $parts       Associative array of URL components like parse_url() returns
  * @param bool  $html_encode HTML Encode the url?
  *
- * @return str Full URL
+ * @return string Full URL
  * @since 1.7.0
  */
 function elgg_http_build_url(array $parts, $html_encode = TRUE) {
@@ -1385,10 +1387,10 @@ function elgg_http_build_url(array $parts, $html_encode = TRUE) {
  * add tokens to the action.  The form view automatically handles
  * tokens.
  *
- * @param str  $url         Full action URL
+ * @param string  $url         Full action URL
  * @param bool $html_encode HTML encode the url? (default: false)
  *
- * @return str URL with action tokens
+ * @return string URL with action tokens
  * @since 1.7.0
  * @link http://docs.elgg.org/Tutorials/Actions
  */
@@ -1447,10 +1449,10 @@ function elgg_http_remove_url_query_element($url, $element) {
 /**
  * Adds an element or elements to a URL's query string.
  *
- * @param str   $url      The URL
+ * @param string $url      The URL
  * @param array $elements Key/value pairs to add to the URL
  *
- * @return str The new URL with the query strings added
+ * @return string The new URL with the query strings added
  * @since 1.7.0
  */
 function elgg_http_add_url_query_elements($url, array $elements) {
@@ -1646,7 +1648,7 @@ $sort_type = SORT_LOCALE_STRING) {
  *
  * @param string $ini_get_arg The INI setting
  *
- * @return true|false Depending on whether it's on or off
+ * @return bool Depending on whether it's on or off
  */
 function ini_get_bool($ini_get_arg) {
 	$temp = strtolower(ini_get($ini_get_arg));
@@ -1662,7 +1664,7 @@ function ini_get_bool($ini_get_arg) {
  *
  * @tip Use this for arithmetic when determining if a file can be uploaded.
  *
- * @param str $setting The php.ini setting
+ * @param string $setting The php.ini setting
  *
  * @return int
  * @since 1.7.0
@@ -1677,8 +1679,10 @@ function elgg_get_ini_setting_in_bytes($setting) {
 	switch($last) {
 		case 'g':
 			$val *= 1024;
+			// fallthrough intentional
 		case 'm':
 			$val *= 1024;
+			// fallthrough intentional
 		case 'k':
 			$val *= 1024;
 	}
@@ -1835,7 +1839,7 @@ function elgg_ajax_page_handler($page) {
  *
  * @param array $page The page array
  *
- * @return void
+ * @return bool
  * @elgg_pagehandler css
  * @access private
  */
@@ -2220,7 +2224,7 @@ function elgg_init() {
  * @param array  $params empty
  *
  * @elgg_plugin_hook unit_tests system
- * @return void
+ * @return array
  * @access private
  */
 function elgg_api_test($hook, $type, $value, $params) {
@@ -2232,7 +2236,7 @@ function elgg_api_test($hook, $type, $value, $params) {
 }
 
 /**#@+
- * Controlls access levels on ElggEntity entities, metadata, and annotations.
+ * Controls access levels on ElggEntity entities, metadata, and annotations.
  *
  * @var int
  */
@@ -2266,7 +2270,7 @@ define('ELGG_ENTITIES_NO_VALUE', 0);
  * referring page.
  *
  * @see forward
- * @var unknown_type
+ * @var int -1
  */
 define('REFERRER', -1);
 
diff --git a/engine/lib/entities.php b/engine/lib/entities.php
index ce736ce05..0361ae195 100644
--- a/engine/lib/entities.php
+++ b/engine/lib/entities.php
@@ -531,6 +531,7 @@ function can_write_to_container($user_guid = 0, $container_guid = 0, $type = 'al
 		// If still not approved, see if the user is a member of the group
 		// @todo this should be moved to the groups plugin/library
 		if (!$return && $user && $container instanceof ElggGroup) {
+			/* @var ElggGroup $container */
 			if ($container->isMember($user)) {
 				$return = true;
 			}
@@ -1463,7 +1464,7 @@ function elgg_list_entities(array $options = array(), $getter = 'elgg_get_entiti
  *
  * @param string $type           The type of entity
  * @param string $subtype        The subtype of entity
- * @param int    $container_guid The container GUID that the entinties belong to
+ * @param int    $container_guid The container GUID that the entities belong to
  * @param int    $site_guid      The site GUID
  * @param string $order_by       Order_by SQL order by clause
  *
@@ -2413,6 +2414,7 @@ function elgg_instanceof($entity, $type = NULL, $subtype = NULL, $class = NULL)
 	$return = ($entity instanceof ElggEntity);
 
 	if ($type) {
+		/* @var ElggEntity $entity */
 		$return = $return && ($entity->getType() == $type);
 	}
 
diff --git a/engine/lib/export.php b/engine/lib/export.php
index ae9be95ce..31afc1b74 100644
--- a/engine/lib/export.php
+++ b/engine/lib/export.php
@@ -11,7 +11,7 @@
  *
  * @param mixed $object The object either an ElggEntity, ElggRelationship or ElggExtender
  *
- * @return the UUID or false
+ * @return string|false the UUID or false
  */
 function get_uuid_from_object($object) {
 	if ($object instanceof ElggEntity) {
@@ -67,7 +67,7 @@ function is_uuid_this_domain($uuid) {
  *
  * @param string $uuid A unique ID
  *
- * @return mixed
+ * @return ElggEntity|false
  */
 function get_entity_from_uuid($uuid) {
 	$uuid = sanitise_string($uuid);
@@ -167,7 +167,7 @@ function exportAsArray($guid) {
  *
  * @param int $guid The GUID.
  *
- * @return xml
+ * @return string XML
  * @see ElggEntity for an example of its usage.
  * @access private
  */
@@ -184,7 +184,7 @@ function export($guid) {
  * @param string $xml XML string
  *
  * @return bool
- * @throws Exception if there was a problem importing the data.
+ * @throws ImportException if there was a problem importing the data.
  * @access private
  */
 function import($xml) {
diff --git a/engine/lib/extender.php b/engine/lib/extender.php
index 538f601e1..8756e051b 100644
--- a/engine/lib/extender.php
+++ b/engine/lib/extender.php
@@ -86,6 +86,7 @@ function oddmetadata_to_elggextender(ElggEntity $entity, ODDMetaData $element) {
  * @return null
  * @elgg_plugin_hook_handler volatile metadata
  * @todo investigate more.
+ * @throws ImportException
  * @access private
  */
 function import_extender_plugin_hook($hook, $entity_type, $returnvalue, $params) {
@@ -94,6 +95,7 @@ function import_extender_plugin_hook($hook, $entity_type, $returnvalue, $params)
 	$tmp = NULL;
 
 	if ($element instanceof ODDMetaData) {
+		/* @var ODDMetaData $element */
 		// Recall entity
 		$entity_uuid = $element->getAttribute('entity_uuid');
 		$entity = get_entity_from_uuid($entity_uuid);
diff --git a/engine/lib/filestore.php b/engine/lib/filestore.php
index 93a127257..677fac931 100644
--- a/engine/lib/filestore.php
+++ b/engine/lib/filestore.php
@@ -383,7 +383,7 @@ function file_get_general_file_type($mimetype) {
 /**
  * Delete a directory and all its contents
  *
- * @param str $directory Directory to delete
+ * @param string $directory Directory to delete
  *
  * @return bool
  */
@@ -500,7 +500,7 @@ function filestore_init() {
 /**
  * Unit tests for files
  *
- * @param sting  $hook   unit_test
+ * @param string  $hook   unit_test
  * @param string $type   system
  * @param mixed  $value  Array of tests
  * @param mixed  $params Params
diff --git a/engine/lib/input.php b/engine/lib/input.php
index 6d1646e1a..2d71fb77e 100644
--- a/engine/lib/input.php
+++ b/engine/lib/input.php
@@ -233,6 +233,7 @@ function elgg_clear_sticky_value($form_name, $variable) {
  *     match_owner int    0/1
  *     limit       int    default is 10
  *
+ * @param array $page
  * @return string JSON string is returned and then exit
  * @access private
  */
@@ -290,6 +291,7 @@ function input_livesearch_page_handler($page) {
 				if ($entities = get_data($query)) {
 					foreach ($entities as $entity) {
 						$entity = get_entity($entity->guid);
+						/* @var ElggUser $entity */
 						if (!$entity) {
 							continue;
 						}
@@ -339,6 +341,7 @@ function input_livesearch_page_handler($page) {
 				if ($entities = get_data($query)) {
 					foreach ($entities as $entity) {
 						$entity = get_entity($entity->guid);
+						/* @var ElggGroup $entity */
 						if (!$entity) {
 							continue;
 						}
@@ -386,6 +389,7 @@ function input_livesearch_page_handler($page) {
 				if ($entities = get_data($query)) {
 					foreach ($entities as $entity) {
 						$entity = get_entity($entity->guid);
+						/* @var ElggUser $entity */
 						if (!$entity) {
 							continue;
 						}
diff --git a/engine/lib/languages.php b/engine/lib/languages.php
index 98006f7cd..11722f744 100644
--- a/engine/lib/languages.php
+++ b/engine/lib/languages.php
@@ -77,7 +77,7 @@ function elgg_echo($message_key, $args = array(), $language = "") {
  * @param string $country_code   Standard country code (eg 'en', 'nl', 'es')
  * @param array  $language_array Formatted array of strings
  *
- * @return true|false Depending on success
+ * @return bool Depending on success
  */
 function add_translation($country_code, $language_array) {
 	global $CONFIG;
@@ -177,7 +177,7 @@ function _elgg_load_translations() {
  * @param bool   $load_all If true all languages are loaded, if
  *                         false only the current language + en are loaded
  *
- * @return void
+ * @return bool success
  */
 function register_translations($path, $load_all = false) {
 	global $CONFIG;
diff --git a/engine/lib/mb_wrapper.php b/engine/lib/mb_wrapper.php
index c2f5503e0..68fa69005 100644
--- a/engine/lib/mb_wrapper.php
+++ b/engine/lib/mb_wrapper.php
@@ -11,7 +11,7 @@ if (is_callable('mb_internal_encoding')) {
  * NOTE: This differs from parse_str() by returning the results
  * instead of placing them in the local scope!
  *
- * @param str $str The string
+ * @param string $str The string
  *
  * @return array
  * @since 1.7.0
diff --git a/engine/lib/metadata.php b/engine/lib/metadata.php
index f76c20f24..2fa491963 100644
--- a/engine/lib/metadata.php
+++ b/engine/lib/metadata.php
@@ -277,7 +277,7 @@ $access_id = ACCESS_PRIVATE, $allow_multiple = false) {
  *                                   all metadata that match the query instead of returning
  *                                   ElggMetadata objects.
  *
- * @return mixed
+ * @return ElggMetadata[]|mixed
  * @since 1.8.0
  */
 function elgg_get_metadata(array $options = array()) {
@@ -412,7 +412,7 @@ function elgg_enable_metadata(array $options) {
  *
  *  metadata_owner_guids => NULL|ARR guids for metadata owners
  *
- * @return mixed If count, int. If not count, array. false on errors.
+ * @return ElggEntity[]|mixed If count, int. If not count, array. false on errors.
  * @since 1.7.0
  */
 function elgg_get_entities_from_metadata(array $options = array()) {
@@ -461,7 +461,7 @@ function elgg_get_entities_from_metadata(array $options = array()) {
  * @param array|null $order_by_metadata Array of names / direction
  * @param array|null $owner_guids       Array of owner GUIDs
  *
- * @return FALSE|array False on fail, array('joins', 'wheres')
+ * @return false|array False on fail, array('joins', 'wheres')
  * @since 1.7.0
  * @access private
  */
diff --git a/engine/lib/metastrings.php b/engine/lib/metastrings.php
index cf6dd4d98..264d2ba2c 100644
--- a/engine/lib/metastrings.php
+++ b/engine/lib/metastrings.php
@@ -663,9 +663,10 @@ function elgg_normalize_metastrings_options(array $options = array()) {
  *
  * @param int    $id      The object's ID
  * @param string $enabled Value to set to: yes or no
- * @param string $type    The type of table to use: metadata or anntations
+ * @param string $type    The type of table to use: metadata or annotations
  *
  * @return bool
+ * @throws InvalidParameterException
  * @since 1.8.0
  * @access private
  */
@@ -740,7 +741,7 @@ function elgg_batch_metastring_based_objects(array $options, $callback, $inc_off
  *
  * @param int    $id   The metastring-based object's ID
  * @param string $type The type: annotation or metadata
- * @return mixed
+ * @return ElggMetadata|ElggAnnotation
  *
  * @since 1.8.0
  * @access private
diff --git a/engine/lib/navigation.php b/engine/lib/navigation.php
index 86624cd7c..0e8914bbb 100644
--- a/engine/lib/navigation.php
+++ b/engine/lib/navigation.php
@@ -126,6 +126,7 @@ function elgg_unregister_menu_item($menu_name, $item_name) {
 	}
 
 	foreach ($CONFIG->menus[$menu_name] as $index => $menu_object) {
+		/* @var ElggMenuItem $menu_object */
 		if ($menu_object->getName() == $item_name) {
 			unset($CONFIG->menus[$menu_name][$index]);
 			return true;
@@ -152,6 +153,7 @@ function elgg_is_menu_item_registered($menu_name, $item_name) {
 	}
 
 	foreach ($CONFIG->menus[$menu_name] as $index => $menu_object) {
+		/* @var ElggMenuItem $menu_object */
 		if ($menu_object->getName() == $item_name) {
 			return true;
 		}
@@ -345,6 +347,7 @@ function elgg_site_menu_setup($hook, $type, $return, $params) {
 function elgg_river_menu_setup($hook, $type, $return, $params) {
 	if (elgg_is_logged_in()) {
 		$item = $params['item'];
+		/* @var ElggRiverItem $item */
 		$object = $item->getObjectEntity();
 		// comments and non-objects cannot be commented on or liked
 		if (!elgg_in_context('widgets') && $item->annotation_id == 0) {
@@ -388,6 +391,7 @@ function elgg_entity_menu_setup($hook, $type, $return, $params) {
 	}
 	
 	$entity = $params['entity'];
+	/* @var ElggEntity $entity */
 	$handler = elgg_extract('handler', $params, false);
 
 	// access
@@ -433,6 +437,7 @@ function elgg_entity_menu_setup($hook, $type, $return, $params) {
 function elgg_widget_menu_setup($hook, $type, $return, $params) {
 
 	$widget = $params['entity'];
+	/* @var ElggWidget $widget */
 	$show_edit = elgg_extract('show_edit', $params, true);
 
 	$collapse = array(
@@ -481,6 +486,7 @@ function elgg_widget_menu_setup($hook, $type, $return, $params) {
  */
 function elgg_annotation_menu_setup($hook, $type, $return, $params) {
 	$annotation = $params['annotation'];
+	/* @var ElggAnnotation $annotation */
 
 	if ($annotation->name == 'generic_comment' && $annotation->canEdit()) {
 		$url = elgg_http_add_url_query_elements('action/comments/delete', array(
diff --git a/engine/lib/notification.php b/engine/lib/notification.php
index 09ebc9541..4191407fc 100644
--- a/engine/lib/notification.php
+++ b/engine/lib/notification.php
@@ -237,6 +237,7 @@ function set_user_notification_setting($user_guid, $method, $value) {
  * @param array      $params  Optional parameters (none taken in this instance)
  *
  * @return bool
+ * @throws NotificationException
  * @access private
  */
 function email_notify_handler(ElggEntity $from, ElggUser $to, $subject, $message,
@@ -288,6 +289,7 @@ array $params = NULL) {
  * @param array  $params  Optional parameters (none used in this function)
  *
  * @return bool
+ * @throws NotificationException
  * @since 1.7.2
  */
 function elgg_send_email($from, $to, $subject, $body, array $params = NULL) {
@@ -422,7 +424,7 @@ function register_notification_object($entity_type, $object_subtype, $language_n
  * @param int $user_guid   The GUID of the user who wants to follow a user's content
  * @param int $author_guid The GUID of the user whose content the user wants to follow
  *
- * @return true|false Depending on success
+ * @return bool Depending on success
  */
 function register_notification_interest($user_guid, $author_guid) {
 	return add_entity_relationship($user_guid, 'notify', $author_guid);
@@ -434,7 +436,7 @@ function register_notification_interest($user_guid, $author_guid) {
  * @param int $user_guid   The GUID of the user who is following a user's content
  * @param int $author_guid The GUID of the user whose content the user wants to unfollow
  *
- * @return true|false Depending on success
+ * @return bool Depending on success
  */
 function remove_notification_interest($user_guid, $author_guid) {
 	return remove_entity_relationship($user_guid, 'notify', $author_guid);
@@ -450,12 +452,13 @@ function remove_notification_interest($user_guid, $author_guid) {
  * @param string $object_type mixed
  * @param mixed  $object      The object created
  *
- * @return void
+ * @return bool
  * @access private
  */
 function object_notifications($event, $object_type, $object) {
 	// We only want to trigger notification events for ElggEntities
 	if ($object instanceof ElggEntity) {
+		/* @var ElggEntity $object */
 
 		// Get config data
 		global $CONFIG, $SESSION, $NOTIFICATION_HANDLERS;
@@ -495,6 +498,7 @@ function object_notifications($event, $object_type, $object) {
 					'type' => 'user',
 					'limit' => false
 				));
+				/* @var ElggUser[] $interested_users */
 
 				if ($interested_users && is_array($interested_users)) {
 					foreach ($interested_users as $user) {
diff --git a/engine/lib/objects.php b/engine/lib/objects.php
index 852bdb793..81b6b7f12 100644
--- a/engine/lib/objects.php
+++ b/engine/lib/objects.php
@@ -102,7 +102,7 @@ function get_object_sites($object_guid, $limit = 10, $offset = 0) {
 /**
  * Runs unit tests for ElggObject
  *
- * @param sting  $hook   unit_test
+ * @param string  $hook   unit_test
  * @param string $type   system
  * @param mixed  $value  Array of tests
  * @param mixed  $params Params
diff --git a/engine/lib/output.php b/engine/lib/output.php
index 9295f2173..fefb94b3e 100644
--- a/engine/lib/output.php
+++ b/engine/lib/output.php
@@ -12,7 +12,7 @@
  *
  * @param string $text The input string
  *
- * @return string The output stirng with formatted links
+ * @return string The output string with formatted links
  **/
 function parse_urls($text) {
 	// @todo this causes problems with <attr = "val">
@@ -421,7 +421,7 @@ function _elgg_html_decode($string) {
 /**
  * Unit tests for Output
  *
- * @param sting  $hook   unit_test
+ * @param string  $hook   unit_test
  * @param string $type   system
  * @param mixed  $value  Array of tests
  * @param mixed  $params Params
diff --git a/engine/lib/pageowner.php b/engine/lib/pageowner.php
index 94765feee..bf5901aad 100644
--- a/engine/lib/pageowner.php
+++ b/engine/lib/pageowner.php
@@ -39,7 +39,7 @@ function elgg_get_page_owner_guid($guid = 0) {
  *
  * @note Access is disabled when getting the page owner entity.
  *
- * @return ElggEntity|false The current page owner or false if none.
+ * @return ElggUser|ElggGroup|false The current page owner or false if none.
  *
  * @since 1.8.0
  */
diff --git a/engine/lib/plugins.php b/engine/lib/plugins.php
index 94aff277e..3a42cb9b8 100644
--- a/engine/lib/plugins.php
+++ b/engine/lib/plugins.php
@@ -107,6 +107,7 @@ function elgg_generate_plugin_entities() {
 	$old_access = access_get_show_hidden_status();
 	access_show_hidden_entities(true);
 	$known_plugins = elgg_get_entities_from_relationship($options);
+	/* @var ElggPlugin[] $known_plugins */
 
 	if (!$known_plugins) {
 		$known_plugins = array();
@@ -192,7 +193,7 @@ function _elgg_cache_plugin_by_id(ElggPlugin $plugin) {
  * Returns an ElggPlugin object with the path $path.
  *
  * @param string $plugin_id The id (dir name) of the plugin. NOT the guid.
- * @return mixed ElggPlugin or false.
+ * @return ElggPlugin|false
  * @since 1.8.0
  */
 function elgg_get_plugin_from_id($plugin_id) {
@@ -360,7 +361,7 @@ function elgg_load_plugins() {
  *
  * @param string $status      The status of the plugins. active, inactive, or all.
  * @param mixed  $site_guid   Optional site guid
- * @return array
+ * @return ElggPlugin[]
  * @since 1.8.0
  * @access private
  */
@@ -861,9 +862,9 @@ function elgg_set_plugin_user_setting($name, $value, $user_guid = null, $plugin_
 /**
  * Unsets a user-specific plugin setting
  *
- * @param str $name      Name of the setting
+ * @param string $name      Name of the setting
  * @param int $user_guid Defaults to logged in user
- * @param str $plugin_id Defaults to contextual plugin name
+ * @param string $plugin_id Defaults to contextual plugin name
  *
  * @return bool
  * @since 1.8.0
@@ -1087,7 +1088,7 @@ function plugin_run_once() {
 /**
  * Runs unit tests for the entity objects.
  *
- * @param sting  $hook   unit_test
+ * @param string  $hook   unit_test
  * @param string $type   system
  * @param mixed  $value  Array of tests
  * @param mixed  $params Params
diff --git a/engine/lib/relationships.php b/engine/lib/relationships.php
index 41bfa4e73..74954b4ff 100644
--- a/engine/lib/relationships.php
+++ b/engine/lib/relationships.php
@@ -12,7 +12,7 @@
  *
  * @param stdClass $row Database row from the relationship table
  *
- * @return stdClass or ElggMetadata
+ * @return ElggRelationship|stdClass
  * @access private
  */
 function row_to_elggrelationship($row) {
@@ -28,7 +28,7 @@ function row_to_elggrelationship($row) {
  *
  * @param int $id The ID of a relationship
  *
- * @return mixed
+ * @return ElggRelationship|false
  */
 function get_relationship($id) {
 	global $CONFIG;
@@ -220,7 +220,7 @@ function remove_entity_relationships($guid_one, $relationship = "", $inverse = f
  * @param int  $guid                 The GUID of the relationship owner
  * @param bool $inverse_relationship Inverse relationship owners?
  *
- * @return mixed
+ * @return ElggRelationship[]
  */
 function get_entity_relationships($guid, $inverse_relationship = FALSE) {
 	global $CONFIG;
@@ -259,7 +259,7 @@ function get_entity_relationships($guid, $inverse_relationship = FALSE) {
  *
  * 	inverse_relationship => BOOL Inverse the relationship
  *
- * @return mixed If count, int. If not count, array. false on errors.
+ * @return ElggEntity[]|mixed If count, int. If not count, array. false on errors.
  * @since 1.7.0
  */
 function elgg_get_entities_from_relationship($options) {
@@ -316,7 +316,7 @@ function elgg_get_entities_from_relationship($options) {
  *                                     Provide in table.column format.
  * @param string $relationship         Relationship string
  * @param int    $relationship_guid    Entity guid to check
- * @param string $inverse_relationship Inverse relationship check?
+ * @param bool $inverse_relationship Inverse relationship check?
  *
  * @return mixed
  * @since 1.7.0
@@ -381,7 +381,7 @@ function elgg_list_entities_from_relationship(array $options = array()) {
  *
  * @param array $options An options array compatible with
  *                       elgg_get_entities_from_relationship()
- * @return mixed int If count, int. If not count, array. false on errors.
+ * @return ElggEntity[]|mixed int If count, int. If not count, array. false on errors.
  * @since 1.8.0
  */
 function elgg_get_entities_from_relationship_count(array $options = array()) {
@@ -398,7 +398,7 @@ function elgg_get_entities_from_relationship_count(array $options = array()) {
  *
  * @param array $options Options array
  *
- * @return array
+ * @return string
  * @since 1.8.0
  */
 function elgg_list_entities_from_relationship_count($options) {
@@ -499,7 +499,7 @@ function already_attached($guid_one, $guid_two) {
  * @param int    $guid Entity GUID
  * @param string $type The type of object to return e.g. 'file', 'friend_of' etc
  *
- * @return an array of objects
+ * @return ElggEntity[]
  * @access private
  */
 function get_attachments($guid, $type = "") {
@@ -586,6 +586,7 @@ function import_relationship_plugin_hook($hook, $entity_type, $returnvalue, $par
  *
  * @elgg_event_handler export all
  * @return mixed
+ * @throws InvalidParameterException
  * @access private
  */
 function export_relationship_plugin_hook($hook, $entity_type, $returnvalue, $params) {
@@ -624,9 +625,10 @@ function export_relationship_plugin_hook($hook, $entity_type, $returnvalue, $par
  * @access private
  */
 function relationship_notification_hook($event, $type, $object) {
-
+	/* @var ElggRelationship $object */
 	$user_one = get_entity($object->guid_one);
 	$user_two = get_entity($object->guid_two);
+	/* @var ElggUser $user_one */
 
 	return notify_user($object->guid_two,
 			$object->guid_one,
diff --git a/engine/lib/river.php b/engine/lib/river.php
index 33f34360e..148fee051 100644
--- a/engine/lib/river.php
+++ b/engine/lib/river.php
@@ -644,7 +644,7 @@ function update_river_access_by_object($object_guid, $access_id) {
 }
 
 /**
- * Page handler for activiy
+ * Page handler for activity
  *
  * @param array $page
  * @return bool
diff --git a/engine/lib/sites.php b/engine/lib/sites.php
index 5a390167d..fe9af8c7a 100644
--- a/engine/lib/sites.php
+++ b/engine/lib/sites.php
@@ -242,7 +242,7 @@ function get_site_domain($guid) {
 /**
  * Unit tests for sites
  *
- * @param sting  $hook   unit_test
+ * @param string $hook   unit_test
  * @param string $type   system
  * @param mixed  $value  Array of tests
  * @param mixed  $params Params
diff --git a/engine/lib/system_log.php b/engine/lib/system_log.php
index 53fa24557..8149d3fac 100644
--- a/engine/lib/system_log.php
+++ b/engine/lib/system_log.php
@@ -22,7 +22,7 @@
  * @param int       $timebefore Lower time limit
  * @param int       $timeafter  Upper time limit
  * @param int       $object_id  GUID of an object
- * @param str       $ip_address The IP address.
+ * @param string    $ip_address The IP address.
  * @return mixed
  */
 function get_system_log($by_user = "", $event = "", $class = "", $type = "", $subtype = "",
@@ -166,6 +166,7 @@ function system_log($object, $event) {
 
 	if ($object instanceof Loggable) {
 
+		/* @var ElggEntity|ElggExtender $object */
 		if (datalist_get('version') < 2012012000) {
 			// this is a site that doesn't have the ip_address column yet
 			return;
diff --git a/engine/lib/tags.php b/engine/lib/tags.php
index a0887d0f3..a25bd7d33 100644
--- a/engine/lib/tags.php
+++ b/engine/lib/tags.php
@@ -48,7 +48,7 @@ function calculate_tag_size($min, $max, $number_of_tags, $buckets = 6) {
  * @param array $tags    The array of tags.
  * @param int   $buckets The number of buckets
  *
- * @return An associated array of tags with a weighting, this can then be mapped to a display class.
+ * @return array An associated array of tags with a weighting, this can then be mapped to a display class.
  * @access private
  */
 function generate_tag_cloud(array $tags, $buckets = 6) {
@@ -114,8 +114,8 @@ function generate_tag_cloud(array $tags, $buckets = 6) {
  *
  * 	joins => array() Additional joins
  *
- * @return 	false/array - if no tags or error, false
- * 			otherwise, array of objects with ->tag and ->total values
+ * @return 	object[]|false 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()) {
diff --git a/engine/lib/upgrade.php b/engine/lib/upgrade.php
index f4f4b16f5..ae4591b0b 100644
--- a/engine/lib/upgrade.php
+++ b/engine/lib/upgrade.php
@@ -360,6 +360,7 @@ function _elgg_upgrade_is_locked() {
 	
 	// Invalidate query cache
 	if ($DB_QUERY_CACHE) {
+		/* @var ElggStaticVariableCache $DB_QUERY_CACHE */
 		$DB_QUERY_CACHE->clear();
 		elgg_log("Query cache invalidated", 'NOTICE');
 	}
diff --git a/engine/lib/users.php b/engine/lib/users.php
index 9d1fba2d4..22ce08e10 100644
--- a/engine/lib/users.php
+++ b/engine/lib/users.php
@@ -290,7 +290,7 @@ function remove_user_admin($user_guid) {
  * @param int $limit     Number of results to return
  * @param int $offset    Any indexing offset
  *
- * @return false|array On success, an array of ElggSites
+ * @return ElggSite[]|false On success, an array of ElggSites
  */
 function get_user_sites($user_guid, $limit = 10, $offset = 0) {
 	$user_guid = (int)$user_guid;
@@ -379,7 +379,7 @@ function user_is_friend($user_guid, $friend_guid) {
  * @param int    $limit     Number of results to return (default 10)
  * @param int    $offset    Indexing offset, if any
  *
- * @return false|array Either an array of ElggUsers or false, depending on success
+ * @return ElggUser[]|false Either an array of ElggUsers or false, depending on success
  */
 function get_user_friends($user_guid, $subtype = ELGG_ENTITIES_ANY_VALUE, $limit = 10,
 $offset = 0) {
@@ -402,7 +402,7 @@ $offset = 0) {
  * @param int    $limit     Number of results to return (default 10)
  * @param int    $offset    Indexing offset, if any
  *
- * @return false|array Either an array of ElggUsers or false, depending on success
+ * @return ElggUser[]|false Either an array of ElggUsers or false, depending on success
  */
 function get_user_friends_of($user_guid, $subtype = ELGG_ENTITIES_ANY_VALUE, $limit = 10,
 $offset = 0) {
@@ -428,7 +428,7 @@ $offset = 0) {
  * @param int    $timelower The earliest time the entity can have been created. Default: all
  * @param int    $timeupper The latest time the entity can have been created. Default: all
  *
- * @return false|array An array of ElggObjects or false, depending on success
+ * @return ElggObject[]|false An array of ElggObjects or false, depending on success
  */
 function get_user_friends_objects($user_guid, $subtype = ELGG_ENTITIES_ANY_VALUE, $limit = 10,
 $offset = 0, $timelower = 0, $timeupper = 0) {
@@ -681,6 +681,8 @@ function send_new_password_request($user_guid) {
 
 	$user = get_entity($user_guid);
 	if ($user) {
+		/* @var ElggUser $user */
+
 		// generate code
 		$code = generate_random_cleartext_password();
 		$user->setPrivateSetting('passwd_conf_code', $code);
@@ -713,6 +715,7 @@ function force_user_password_reset($user_guid, $password) {
 	global $CONFIG;
 
 	$user = get_entity($user_guid);
+		/* @var ElggUser $user */
 
 	if ($user) {
 		$salt = generate_random_cleartext_password(); // Reset the salt
@@ -743,6 +746,7 @@ function execute_new_password_request($user_guid, $conf_code) {
 	$user = get_entity($user_guid);
 
 	if ($user) {
+		/* @var ElggUser $user */
 		$saved_code = $user->getPrivateSetting('passwd_conf_code');
 
 		if ($saved_code && $saved_code == $conf_code) {
@@ -908,6 +912,7 @@ function validate_email_address($address) {
  * @param string $invitecode            An invite code from a friend
  *
  * @return int|false The new user's GUID; false on failure
+ * @throws RegistrationException
  */
 function register_user($username, $password, $name, $email,
 $allow_multiple_emails = false, $friend_guid = 0, $invitecode = '') {
@@ -1233,6 +1238,7 @@ function user_avatar_hook($hook, $entity_type, $returnvalue, $params) {
  */
 function elgg_user_hover_menu($hook, $type, $return, $params) {
 	$user = $params['entity'];
+	/* @var ElggUser $user */
 
 	if (elgg_is_logged_in()) {
 		if (elgg_get_logged_in_user_guid() != $user->guid) {
@@ -1309,7 +1315,12 @@ function elgg_user_hover_menu($hook, $type, $return, $params) {
 /**
  * Setup the menu shown with an entity
  *
+ * @param string $hook
+ * @param string $type
+ * @param array $return
+ * @param array $params
  * @return array
+ *
  * @access private
  */
 function elgg_users_setup_entity_menu($hook, $type, $return, $params) {
@@ -1321,6 +1332,7 @@ function elgg_users_setup_entity_menu($hook, $type, $return, $params) {
 	if (!elgg_instanceof($entity, 'user')) {
 		return $return;
 	}
+	/* @var ElggUser $entity */
 
 	if ($entity->isBanned()) {
 		$banned = elgg_echo('banned');
@@ -1587,7 +1599,7 @@ function users_init() {
 /**
  * Runs unit tests for ElggObject
  *
- * @param sting  $hook   unit_test
+ * @param string $hook   unit_test
  * @param string $type   system
  * @param mixed  $value  Array of tests
  * @param mixed  $params Params
diff --git a/engine/lib/views.php b/engine/lib/views.php
index 8618c2997..9ee7ae00c 100644
--- a/engine/lib/views.php
+++ b/engine/lib/views.php
@@ -1308,7 +1308,7 @@ function elgg_view_form($action, $form_vars = array(), $body_vars = array()) {
 /**
  * View an item in a list
  *
- * @param object $item ElggEntity or ElggAnnotation
+ * @param ElggEntity|ElggAnnotation $item
  * @param array  $vars Additional parameters for the rendering
  *
  * @return string
diff --git a/engine/lib/widgets.php b/engine/lib/widgets.php
index d73dd6330..699462a1b 100644
--- a/engine/lib/widgets.php
+++ b/engine/lib/widgets.php
@@ -336,7 +336,7 @@ function elgg_default_widgets_init() {
  *
  * @param string $event  The event
  * @param string $type   The type of object
- * @param object $entity The entity being created
+ * @param ElggEntity $entity The entity being created
  * @return void
  * @access private
  */
@@ -372,6 +372,7 @@ function elgg_create_default_widgets($event, $type, $entity) {
 				);
 
 				$widgets = elgg_get_entities_from_private_settings($options);
+				/* @var ElggWidget[] $widgets */
 
 				foreach ($widgets as $widget) {
 					// change the container and owner
diff --git a/engine/lib/xml.php b/engine/lib/xml.php
index ff82d7e8a..497459d83 100644
--- a/engine/lib/xml.php
+++ b/engine/lib/xml.php
@@ -104,7 +104,7 @@ function serialise_array_to_xml(array $data, $n = 0) {
  *
  * @param string $xml The XML
  *
- * @return object
+ * @return ElggXMLElement
  */
 function xml_to_object($xml) {
 	return new ElggXMLElement($xml);