Refs #2450: Documented ElggObject.

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

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