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

18 files changed, 75 insertions, 35 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";