Refs #2450: Documented ElggObject.

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

1 files changed, 48 insertions, 27 deletions

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(