Refs #2450: Documented ElggSite, clarified some docs on ElggObject.

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

2 files changed, 105 insertions, 41 deletions

diff --git a/engine/classes/ElggObject.php b/engine/classes/ElggObject.php
index 50ebe2d2d..d19e1c844 100644
--- a/engine/classes/ElggObject.php
+++ b/engine/classes/ElggObject.php
@@ -33,9 +33,11 @@ class ElggObject extends ElggEntity {
 	 * 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.
+	 *
+	 * If an argument is passed attempt to load a full Object entity.  Arguments
+	 * can be:
+	 *  - The GUID of an object entity.
+	 *  - A DB result object with a guid property
 	 *
 	 * @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
diff --git a/engine/classes/ElggSite.php b/engine/classes/ElggSite.php
index 06cdf70ea..08d47ade5 100644
--- a/engine/classes/ElggSite.php
+++ b/engine/classes/ElggSite.php
@@ -1,10 +1,26 @@
 <?php
 /**
- * ElggSite
- * Representation of a "site" in the system.
- * @author Curverider Ltd <info@elgg.com>
- * @package Elgg
- * @subpackage Core
+ * A Site entity.
+ *
+ * ElggSite represents a single site entity.
+ *
+ * An ElggSite object is an ElggEntity child class with the subtype
+ * of "site."  It is created upon installation and hold all the
+ * information about a site:
+ *  - name
+ *  - description
+ *  - url
+ *
+ * Every ElggEntity (except ElggSite) belongs to a site.
+ *
+ * @internal ElggSite represents a single row from the sites_entity
+ * table, as well as the corresponding ElggEntity row from the entities table.
+ *
+ * @warning Multiple site support isn't fully developed.
+ *
+ * @package Elgg.Core
+ * @subpackage DataMode.Site
+ * @link http://docs.elgg.org/DataModel/Sites
  */
 class ElggSite extends ElggEntity {
 	/**
@@ -24,11 +40,19 @@ class ElggSite extends ElggEntity {
 	}
 
 	/**
-	 * Construct a new site object, optionally from a given id value.
+	 * Load or create a new ElggSite.
 	 *
-	 * @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 site.
+	 * If no arguments are passed, create a new entity.
+	 *
+	 * If an argument is passed attempt to load a full Site entity.  Arguments
+	 * can be:
+	 *  - The GUID of a site entity.
+	 *  - A URL as stored in ElggSite->url
+	 *  - A DB result object with a guid property
+	 *
+	 * @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 ElggSite
 	 */
 	function __construct($guid = null) {
 		$this->initialise_attributes();
@@ -45,7 +69,7 @@ class ElggSite extends ElggEntity {
 			// Is $guid is an ElggSite? Use a copy constructor
 			else if ($guid instanceof ElggSite) {
 				elgg_deprecated_notice('This type of usage of the ElggSite constructor was deprecated. Please use the clone method.', 1.7);
-				
+
 				foreach ($guid->attributes as $key => $value) {
 					$this->attributes[$key] = $value;
 				}
@@ -78,11 +102,11 @@ class ElggSite extends ElggEntity {
 	}
 
 	/**
-	 * Override the load function.
-	 * This function will ensure that all data is loaded (were possible), so
-	 * if only part of the ElggSite is loaded, it'll load the rest.
+	 * Loads the full ElggSite when given a guid.
 	 *
 	 * @param int $guid
+	 * @return bool
+	 * @throws InvalidClassException
 	 */
 	protected function load($guid) {
 		// Test to see if we have the generic stuff
@@ -112,7 +136,11 @@ class ElggSite extends ElggEntity {
 	}
 
 	/**
-	 * Override the save function.
+	 * Saves site-specific attributes.
+	 *
+	 * @internal Site attributes are saved in the sites_entity table.
+	 *
+	 * @return bool
 	 */
 	public function save() {
 		// Save generic stuff
@@ -125,7 +153,12 @@ class ElggSite extends ElggEntity {
 	}
 
 	/**
-	 * Delete this site.
+	 * Delete the site.
+	 *
+	 * @note You cannot delete the current site.
+	 *
+	 * @return bool
+	 * @throws SecurityException
 	 */
 	public function delete() {
 		global $CONFIG;
@@ -137,9 +170,13 @@ class ElggSite extends ElggEntity {
 	}
 
 	/**
-	 * Disable override to add safety rail.
+	 * Disable the site
+	 *
+	 * @note You cannot disable the current site.
 	 *
-	 * @param unknown_type $reason
+	 * @param string $reason
+	 * @return bool
+	 * @throws SecurityException
 	 */
 	public function disable($reason = "") {
 		global $CONFIG;
@@ -152,7 +189,7 @@ class ElggSite extends ElggEntity {
 	}
 
 	/**
-	 * Return a list of users using this site.
+	 * Returns an array of ElggUser entities who are members of the site.
 	 *
 	 * @param int $limit
 	 * @param int $offset
@@ -163,47 +200,52 @@ class ElggSite extends ElggEntity {
 	}
 
 	/**
-	 * Add a user to the site.
+	 * Adds a user to the site.
 	 *
 	 * @param int $user_guid
+	 * @return bool
 	 */
 	public function addUser($user_guid) {
 		return add_site_user($this->getGUID(), $user_guid);
 	}
 
 	/**
-	 * Remove a site user.
+	 * Removes a user from the site.
 	 *
 	 * @param int $user_guid
+	 * @return bool
 	 */
 	public function removeUser($user_guid) {
 		return remove_site_user($this->getGUID(), $user_guid);
 	}
 
 	/**
-	 * Get an array of member ElggObjects.
+	 * Returns an array of ElggObject entities that belong to the site.
 	 *
 	 * @param string $subtype
 	 * @param int $limit
 	 * @param int $offset
+	 * @return array
 	 */
 	public function getObjects($subtype="", $limit = 10, $offset = 0) {
 		get_site_objects($this->getGUID(), $subtype, $limit, $offset);
 	}
 
 	/**
-	 * Add an object to the site.
+	 * Adds an object to the site.
 	 *
-	 * @param int $user_id
+	 * @param int $object_guid
+	 * @return bool
 	 */
 	public function addObject($object_guid) {
 		return add_site_object($this->getGUID(), $object_guid);
 	}
 
 	/**
-	 * Remove a site user.
+	 * Remvoes an object from the site.
 	 *
-	 * @param int $user_id
+	 * @param int $object_guid
+	 * @return bool
 	 */
 	public function removeObject($object_guid) {
 		return remove_site_object($this->getGUID(), $object_guid);
@@ -216,15 +258,20 @@ class ElggSite extends ElggEntity {
 	 * @param int $limit
 	 * @param int $offset
 	 * @return unknown
+	 * @todo Unimplemented
 	 */
 	public function getCollections($subtype="", $limit = 10, $offset = 0) {
 		get_site_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(
@@ -233,38 +280,53 @@ class ElggSite extends ElggEntity {
 			'url',
 		));
 	}
-	
+
+	/**
+	 * Halts bootup and redirects to the site front page
+	 * if site is in walled garden mode, no user is logged in,
+	 * and the URL is not a public page.
+	 *
+	 * @link http://docs.elgg.org/Tutorials/WalledGarden
+	 */
 	public function check_walled_garden() {
 		global $CONFIG;
-		
+
 		if ($CONFIG->walled_garden && !isloggedin()) {
 			// hook into the index system call at the highest priority
 			register_plugin_hook('index', 'system', 'elgg_walled_garden_index', 1);
-			
+
 			if (!$this->is_public_page()) {
 				register_error(elgg_echo('loggedinrequired'));
 				forward();
 			}
 		}
 	}
-	
+
+	/**
+	 * Returns if a URL is public for this site when in Walled Garden mode.
+	 *
+	 * Pages are registered to be public by {@elgg_plugin_hook public_pages walled_garden}.
+	 *
+	 * @param string $url Defaults to the current URL.
+	 * @return bool
+	 */
 	public function is_public_page($url='') {
 		global $CONFIG;
-		
+
 		if (empty($url)) {
 			$url = current_page_url();
-			
+
 			// do not check against URL queries
 			if ($pos = strpos($url, '?')) {
 				$url = substr($url, 0, $pos);
 			}
 		}
-		
+
 		// always allow index page
 		if ($url == $CONFIG->url) {
 			return TRUE;
 		}
-		
+
 		// default public pages
 		$defaults = array(
 			'action/login',
@@ -279,12 +341,12 @@ class ElggSite extends ElggEntity {
 			'_css/css\.css',
 			'_css/js\.php',
 		);
-		
+
 		// include a hook for plugin authors to include public pages
 		$plugins = trigger_plugin_hook('public_pages', 'walled_garden', NULL, array());
-		
+
 		// lookup admin-specific public pages
-		
+
 		// allow public pages
 		foreach (array_merge($defaults, $plugins) as $public) {
 			$pattern = "`^{$CONFIG->url}$public/*$`i";
@@ -292,7 +354,7 @@ class ElggSite extends ElggEntity {
 				return TRUE;
 			}
 		}
-		
+
 		// non-public page
 		return FALSE;
 	}