Added comments to several undocumented methods

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

3 files changed, 47 insertions, 18 deletions

diff --git a/engine/classes/ElggAnnotation.php b/engine/classes/ElggAnnotation.php
index 60a79bac9..913d909c5 100644
--- a/engine/classes/ElggAnnotation.php
+++ b/engine/classes/ElggAnnotation.php
@@ -14,6 +14,13 @@
  */
 class ElggAnnotation extends ElggExtender {
 
+	/**
+	 * (non-PHPdoc)
+	 *
+	 * @see ElggData::initializeAttributes()
+	 *
+	 * @return void
+	 */
 	protected function initializeAttributes() {
 		parent::initializeAttributes();
 
diff --git a/engine/classes/ElggData.php b/engine/classes/ElggData.php
index 4591c499d..96de1bc8f 100644
--- a/engine/classes/ElggData.php
+++ b/engine/classes/ElggData.php
@@ -1,11 +1,18 @@
 <?php
+/**
+ * A generic class that contains shared code b/w
+ * ElggExtender, ElggEntity, and ElggRelationship
+ *
+ * @package    Elgg.Core
+ * @subpackage DataModel
+ */
 abstract class ElggData implements
 	Loggable,	// Can events related to this object class be logged
 	Iterator,	// Override foreach behaviour
 	ArrayAccess, // Override for array access
 	Exportable
 {
-	
+
 	/**
 	 * The main attributes of an entity.
 	 * Holds attributes to save to database
@@ -15,7 +22,7 @@ abstract class ElggData implements
 	 * Any field not appearing in this will be viewed as a
 	 */
 	protected $attributes = array();
-	
+
 	/**
 	 * Initialize the attributes array.
 	 *
@@ -28,7 +35,7 @@ abstract class ElggData implements
 		if (!is_array($this->attributes)) {
 			$this->attributes = array();
 		}
-		
+
 		$this->attributes['time_created'] = '';
 	}
 
@@ -54,7 +61,7 @@ abstract class ElggData implements
 	public function __set($name, $value) {
 		return $this->set($name, $value);
 	}
-	
+
 	/**
 	 * Test if property is set either as an attribute or metadata.
 	 *
@@ -67,32 +74,47 @@ abstract class ElggData implements
 	function __isset($name) {
 		return $this->$name !== NULL;
 	}
-	
+
+	/**
+	 * Fetch the specified attribute
+	 *
+	 * @param string $name The attribute to fetch
+	 *
+	 * @return mixed The attribute, if it exists.  Otherwise, null.
+	 */
 	abstract protected function get($name);
-	
+
+	/**
+	 * Set the specified attribute
+	 *
+	 * @param string $name  The attribute to set
+	 * @param mixed  $value The value to set it to
+	 *
+	 * @return The success of your set funtion?
+	 */
 	abstract protected function set($name, $value);
-	
+
 	/**
 	 * Get a URL for this object
-	 * 
+	 *
 	 * @return string
 	 */
 	abstract public function getURL();
-	
+
 	/**
 	 * Save this data to the appropriate database table.
 	 *
 	 * @return bool
 	 */
 	abstract public function save();
-	
+
 	/**
 	 * Delete this data.
 	 *
 	 * @return bool
 	 */
 	abstract public function delete();
-		
+
 	/**
 	 * Returns the UNIX epoch time that this entity was created
 	 *
@@ -101,7 +123,7 @@ abstract class ElggData implements
 	public function getTimeCreated() {
 		return $this->time_created;
 	}
-	
+
 	/*
 	 *  SYSTEM LOG INTERFACE
 	 */
@@ -122,7 +144,7 @@ abstract class ElggData implements
 	 * @deprecated 1.8 Use getOwner() instead
 	 */
 	public function getObjectOwnerGUID() {
-		elgg_deprecated_notice("The method getObjectOwnerGUID() was deprecated in Elgg 1.8.  Use getOwner() instead.", 1.8);
+		elgg_deprecated_notice("getObjectOwnerGUID() was deprecated.  Use getOwner().", 1.8);
 		return $this->owner_guid;
 	}
 
diff --git a/engine/classes/ElggEntity.php b/engine/classes/ElggEntity.php
index 66aca035e..96d18142f 100644
--- a/engine/classes/ElggEntity.php
+++ b/engine/classes/ElggEntity.php
@@ -23,7 +23,7 @@
  * instead of this class.
  *
  * @package    Elgg.Core
- * @subpackage DataMode.Entities
+ * @subpackage DataModel.Entities
  * @link       http://docs.elgg.org/DataModel/ElggEntity
  */
 abstract class ElggEntity extends ElggData implements
@@ -83,7 +83,7 @@ abstract class ElggEntity extends ElggData implements
 	 */
 	protected function initializeAttributes() {
 		parent::initializeAttributes();
-		
+
 		initialise_entity_cache();
 
 		$this->attributes['guid'] = "";
@@ -654,9 +654,9 @@ abstract class ElggEntity extends ElggData implements
 	 * Can a user write to this entity
 	 *
 	 * @param int $user_guid The user.
-	 * @param string $type The type of entity we're looking to write 
+	 * @param string $type The type of entity we're looking to write
  	 * @param string $subtype The subtype of the entity we're looking to write
- 	 * 
+ 	 *
 	 * @return bool
 	 */
 	public function canWriteToContainer($user_guid = 0, $type = 'all', $subtype = 'all') {
@@ -754,7 +754,7 @@ abstract class ElggEntity extends ElggData implements
 	public function getContainerEntity() {
 		return get_entity($this->getContainer());
 	}
-	
+
 	/**
 	 * Returns the UNIX epoch time that this entity was last updated
 	 *