From 6a49dcf1082e3047d3c92a3b3b3bb43efa2b2c74 Mon Sep 17 00:00:00 2001
From: brettp <brettp@36083f99-b078-4883-b0ff-0f9b5a30f544>
Date: Wed, 22 Sep 2010 15:53:43 +0000
Subject: Refs #2450: Documented ElggObject.

git-svn-id: http://code.elgg.org/elgg/trunk@6955 36083f99-b078-4883-b0ff-0f9b5a30f544
---
 engine/classes/ElggObject.php | 75 +++++++++++++++++++++++++++----------------
 1 file changed, 48 insertions(+), 27 deletions(-)

(limited to 'engine/classes/ElggObject.php')

diff --git a/engine/classes/ElggObject.php b/engine/classes/ElggObject.php
index af67ef3f6..0bdfb064f 100644
--- a/engine/classes/ElggObject.php
+++ b/engine/classes/ElggObject.php
@@ -1,18 +1,24 @@
 <?php
-
 /**
- * ElggObject
- * Representation of an "object" in the system.
+ * Elgg Object
+ *
+ * Elgg objects are the most common means of storing information in the database.
+ * They are a child class of ElggEntity, so receive all the benefits of the Entities,
+ * but also include a title and description field.
+ *
+ * An ElggObject represents a row from the objects_entity table, as well
+ * as the related row in the entities table as represented by the parent
+ * ElggEntity object.
+ *
+ * @internal Title and description are stored in the objects_entity table.
  *
- * @package Elgg
- * @subpackage Core
+ * @package Elgg.Core
+ * @subpackage DataModel.Object
  */
 class ElggObject extends ElggEntity {
 	/**
-	 * Initialise the attributes array.
-	 * This is vital to distinguish between metadata and base parameters.
-	 *
-	 * Place your base parameters here.
+	 * Initialise the attributes array to include the type,
+	 * title, and description.
 	 */
 	protected function initialise_attributes() {
 		parent::initialise_attributes();
@@ -24,11 +30,16 @@ class ElggObject extends ElggEntity {
 	}
 
 	/**
-	 * Construct a new object entity, optionally from a given id value.
+	 * Load or create a new ElggObject.
+	 *
+	 * If no arguments are passed, create a new entity.
+	 * If an argument is passed as an int, attempt to load that object by guid.
+	 * If an argument is passed as an object, assume that it is as database result object and attempt to load
+	 * by $obj->guid.
 	 *
-	 * @param mixed $guid If an int, load that GUID.
-	 * 	If a db row then will attempt to load the rest of the data.
-	 * @throws Exception if there was a problem creating the object.
+	 * @param mixed $guid If an int, load that GUID.  If a db row then will attempt to load the rest of the data.
+	 * @throws IOException If passed an incorrect guid
+	 * @throws InvalidParameterException If passed an Elgg* Entity that isn't an ElggObject
 	 */
 	function __construct($guid = null) {
 		$this->initialise_attributes();
@@ -70,12 +81,11 @@ class ElggObject extends ElggEntity {
 	}
 
 	/**
-	 * Override the load function.
-	 * This function will ensure that all data is loaded (were possible), so
-	 * if only part of the ElggObject is loaded, it'll load the rest.
+	 * Loads the full ElggObject when given a guid.
 	 *
 	 * @param int $guid
-	 * @return true|false
+	 * @return bool
+	 * @throws InvalidClassException
 	 */
 	protected function load($guid) {
 		// Test to see if we have the generic stuff
@@ -105,35 +115,42 @@ class ElggObject extends ElggEntity {
 	}
 
 	/**
-	 * Override the save function.
-	 * @return true|false
+	 * Saves object-specific attributes.
+	 *
+	 * @internal Object attributes are saved in the objects_entity table.
+	 *
+	 * @return bool
 	 */
 	public function save() {
-		// Save generic stuff
+		// Save ElggEntity attributes
 		if (!parent::save()) {
 			return false;
 		}
 
-		// Now save specific stuff
+		// Save ElggObject-specific attributes
 		return create_object_entity($this->get('guid'), $this->get('title'), $this->get('description'), $this->get('container_guid'));
 	}
 
 	/**
-	 * Get sites that this object is a member of
+	 * Return sites that this object is a member of
+	 *
+	 * Site membership is determined by relationships and not site_guid.d
 	 *
 	 * @param string $subtype Optionally, the subtype of result we want to limit to
 	 * @param int $limit The number of results to return
 	 * @param int $offset Any indexing offset
+	 * @todo This should be moved to ElggEntity
+	 * @todo Unimplemented
 	 */
 	function getSites($subtype="", $limit = 10, $offset = 0) {
 		return get_site_objects($this->getGUID(), $subtype, $limit, $offset);
 	}
 
 	/**
-	 * Add this object to a particular site
+	 * Add this object to a site
 	 *
 	 * @param int $site_guid The guid of the site to add it to
-	 * @return true|false
+	 * @return bool
 	 */
 	function addToSite($site_guid) {
 		return add_site_object($this->getGUID(), $site_guid);
@@ -152,7 +169,7 @@ class ElggObject extends ElggEntity {
 	}
 
 	/**
-	 * Return the container GUID of this object.
+	 * Returns the container GUID of this object.
 	 *
 	 * @return int
 	 */
@@ -161,7 +178,7 @@ class ElggObject extends ElggEntity {
 	}
 
 	/**
-	 * As getContainer(), but returns the whole entity.
+	 * Returns the contain entity for this object.
 	 *
 	 * @return mixed ElggGroup object or false.
 	 */
@@ -185,10 +202,14 @@ class ElggObject extends ElggEntity {
 	 */
 	//public function getCollections($subtype="", $limit = 10, $offset = 0) { get_object_collections($this->getGUID(), $subtype, $limit, $offset); }
 
-	// EXPORTABLE INTERFACE ////////////////////////////////////////////////////////////
+	/*
+	 * EXPORTABLE INTERFACE
+	 */
 
 	/**
 	 * Return an array of fields which can be exported.
+	 *
+	 * @return array
 	 */
 	public function getExportableValues() {
 		return array_merge(parent::getExportableValues(), array(
-- 
cgit v1.2.3