Misja Hoebe <misja@curverider.co.uk> More docstring fixes

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

12 files changed, 244 insertions, 30 deletions

diff --git a/endpoints/rest.php b/endpoints/rest.php
index 321d730c1..862540e57 100644
--- a/endpoints/rest.php
+++ b/endpoints/rest.php
@@ -11,7 +11,9 @@
 	 * @link http://elgg.org/
 	 */
 
-	// Include required files
+	/**
+	 *  Start the Elgg engine
+	 */
 	require_once('../engine/start.php');
 	global $CONFIG;
 	
diff --git a/engine/lib/annotations.php b/engine/lib/annotations.php
index f37e22154..c71d235f8 100644
--- a/engine/lib/annotations.php
+++ b/engine/lib/annotations.php
@@ -55,7 +55,7 @@
 		}
 		
 		/**
-		 * Class variable getter overloading
+		 * Class member get overloading
 		 *
 		 * @param string $name
 		 * @return mixed
@@ -65,7 +65,7 @@
 		}
 		
 		/**
-		 * Class variable setter overloading
+		 * Class member set overloading
 		 *
 		 * @param string $name
 		 * @param mixed $value
diff --git a/engine/lib/entities.php b/engine/lib/entities.php
index 64aa902de..a31da1c88 100644
--- a/engine/lib/entities.php
+++ b/engine/lib/entities.php
@@ -12,9 +12,12 @@
 	 */
 
 	/**
-	 * @class ElggEntity The elgg entity superclass
+	 * ElggEntity The elgg entity superclass
 	 * This class holds methods for accessing the main entities table.
+	 * 
 	 * @author Marcus Povey <marcus@dushka.co.uk>
+	 * @package Elgg
+	 * @subpackage Core
 	 */
 	abstract class ElggEntity implements 
 		Exportable, // Allow export of data
@@ -34,6 +37,8 @@
 		 * This is vital to distinguish between metadata and base parameters.
 		 * 
 		 * Place your base parameters here.
+		 * 
+		 * @return void
 		 */
 		protected function initialise_attributes()
 		{
@@ -252,12 +257,60 @@
 			return can_edit_entity($this->getGUID(),$user_guid);

 		}

 		
+		/**
+		 * Enter description here...
+		 *
+		 * @return unknown
+		 * @todo document me
+		 */
 		public function getAccessID() { return $this->get('access_id'); }
+		
+		/**
+		 * Enter description here...
+		 *
+		 * @return unknown
+		 * @todo document me
+		 */
 		public function getGUID() { return $this->get('guid'); }
+		
+		/**
+		 * Enter description here...
+		 *
+		 * @return unknown
+		 * @todo document me
+		 */
 		public function getOwner() { return $this->get('owner_guid'); }
+		
+		/**
+		 * Enter description here...
+		 *
+		 * @return unknown
+		 * @todo document me
+		 */
 		public function getType() { return $this->get('type'); }
+		
+		/**
+		 * Enter description here...
+		 *
+		 * @return unknown
+		 * @todo document me
+		 */
 		public function getSubtype() { return get_subtype_from_id($this->get('subtype')); }
+		
+		/**
+		 * Enter description here...
+		 *
+		 * @return unknown
+		 * @todo document me
+		 */
 		public function getTimeCreated() { return $this->get('time_created'); }
+		
+		/**
+		 * Enter description here...
+		 *
+		 * @return unknown
+		 * @todo document me
+		 */
 		public function getTimeUpdated() { return $this->get('time_updated'); }
 		
 		/**
diff --git a/engine/lib/exceptions.php b/engine/lib/exceptions.php
index 000501196..e797f85bc 100644
--- a/engine/lib/exceptions.php
+++ b/engine/lib/exceptions.php
@@ -14,93 +14,129 @@
 	// Top level //////////////////////////////////////////////////////////////////////////////
 
 	/**
-	 * @class IOException 
+	 * IOException 
 	 * An IO Exception, throw when an IO Exception occurs. Subclass for specific IO Exceptions.
+	 * 
 	 * @author Marcus Povey <marcus@dushka.co.uk>
+	 * @package Elgg
+	 * @subpackage Exceptions
 	 */
 	class IOException extends Exception {}
 
 	/**
-	 * @class ClassException 
+	 * ClassException 
 	 * A class Exception, throw when there is a class error.
+	 * 
 	 * @author Marcus Povey <marcus@dushka.co.uk>
+	 * @package Elgg
+	 * @subpackage Exceptions
 	 */
 	class ClassException extends Exception {}
 
 	/**
-	 * @class ConfigurationException 
+	 * ConfigurationException 
 	 * There is a configuration error
+	 * 
 	 * @author Marcus Povey <marcus@dushka.co.uk>
+	 * @package Elgg
+	 * @subpackage Exceptions
 	 */
 	class ConfigurationException extends Exception {}
 
 	/**
-	 * @class SecurityException 
+	 * SecurityException 
 	 * An Security Exception, throw when a Security Exception occurs. Subclass for specific Security Execeptions (access problems etc)
+	 * 
 	 * @author Marcus Povey <marcus@dushka.co.uk>
+	 * @package Elgg
+	 * @subpackage Exceptions
 	 */
 	class SecurityException extends Exception {}
 
 	/**
-	 * @class ClassNotFoundException 
+	 * ClassNotFoundException 
 	 * An database exception, throw when a database exception happens, subclass if more detail is needed.
+	 * 
 	 * @author Marcus Povey <marcus@dushka.co.uk>
+	 * @package Elgg
+	 * @subpackage Exceptions
 	 */
 	class DatabaseException extends Exception {}
 
 	/**
-	 * @class APIException
+	 * APIException
 	 * The API Exception class, thrown by the API layer when an API call has an issue.
+	 * 
 	 * @author Marcus Povey <marcus@dushka.co.uk>
+	 * @package Elgg
+	 * @subpackage Exceptions
 	 */
 	class APIException extends Exception {}
 	
 	/**
-	 * @class CallException
+	 * CallException
 	 * An exception thrown when there is a problem calling something.
+	 * 
 	 * @author Marcus Povey <marcus@dushka.co.uk>
+	 * @package Elgg
+	 * @subpackage Exceptions
 	 */
 	class CallException extends Exception {}
 	
 	// Class exceptions ///////////////////////////////////////////////////////////////////////
 
 	/**
-	 * @class InvalidClassException 
+	 * InvalidClassException 
 	 * An invalid class Exception, throw when a class is invalid.
+	 * 
 	 * @author Marcus Povey <marcus@dushka.co.uk>
+	 * @package Elgg
+	 * @subpackage Exceptions
 	 */
 	class InvalidClassException extends ClassException {}
 
 	/**
-	 * @class ClassNotFoundException 
+	 * ClassNotFoundException 
 	 * An Class not found Exception, throw when an class can not be found occurs.
+	 * 
 	 * @author Marcus Povey <marcus@dushka.co.uk>
+	 * @package Elgg
+	 * @subpackage Exceptions
 	 */
 	class ClassNotFoundException extends ClassException {}
 	
 	// Configuration exceptions ///////////////////////////////////////////////////////////////
 
 	/**
-	 * @class InstallationException
+	 * InstallationException
 	 * Thrown when there is a major problem with the installation.
+	 * 
 	 * @author Marcus Povey <marcus@dushka.co.uk>
+	 * @package Elgg
+	 * @subpackage Exceptions
 	 */
 	class InstallationException extends ConfigurationException {}
 	
 	// Call exceptions ////////////////////////////////////////////////////////////////////////
 
 	/**
-	 * @class NotImplementedException
+	 * NotImplementedException
 	 * Thrown when a method or function has not been implemented, primarily used in development... you should
 	 * not see these!
+	 * 
 	 * @author Marcus Povey <marcus@dushka.co.uk>
+	 * @package Elgg
+	 * @subpackage Exceptions
 	 */
 	class NotImplementedException extends CallException {}
 	
 	/**
-	 * @class InvalidParameterException
+	 * InvalidParameterException
 	 * A parameter is invalid.
+	 * 
 	 * @author Marcus Povey <marcus@dushka.co.uk>
+	 * @package Elgg
+	 * @subpackage Exceptions
 	 */
 	class InvalidParameterException extends CallException {}
 ?>
\ No newline at end of file
diff --git a/engine/lib/export.php b/engine/lib/export.php
index 8e3376f32..586f5609d 100644
--- a/engine/lib/export.php
+++ b/engine/lib/export.php
@@ -12,6 +12,9 @@
 
 	/**
 	 * Define an interface for all exportable objects.
+	 * 
+	 * @package Elgg
+	 * @subpackage Core
 	 * @author Marcus Povey
 	 */
 	interface Exportable
@@ -318,7 +321,21 @@
 		return $output;
 	}
 	
+	/**
+	 * Export exception
+	 * 
+	 * @package Elgg
+	 * @subpackage Exceptions
+	 *
+	 */
 	class ExportException extends Exception {}
+	
+	/**
+	 * Import exception
+	 *
+	 * @package Elgg
+	 * @subpackage Exceptions
+	 */
 	class ImportException extends Exception {}
 	
 ?>
\ No newline at end of file
diff --git a/engine/lib/extender.php b/engine/lib/extender.php
index aca8a0fca..26166a225 100644
--- a/engine/lib/extender.php
+++ b/engine/lib/extender.php
@@ -12,8 +12,11 @@
 	 */
 
 	/**
-	 * @class ElggExtender 
+	 * ElggExtender 
+	 * 
 	 * @author Marcus Povey
+	 * @package Elgg
+	 * @subpackage Core
 	 */
 	abstract class ElggExtender implements Exportable, Importable
 	{
@@ -23,6 +26,12 @@
 		 */
 		protected $attributes;
 		
+		/**
+		 * Get an attribute
+		 *
+		 * @param string $name
+		 * @return mixed
+		 */
 		protected function get($name) {
 			if (isset($this->attributes[$name])) {
 				
@@ -45,6 +54,13 @@
 			return null;
 		}
 		
+		/**
+		 * Set an attribute
+		 *
+		 * @param string $name
+		 * @param mixed $value
+		 * @return boolean
+		 */
 		protected function set($name, $value) {
 			$this->attributes[$name] = $value;
 			return true;
@@ -80,6 +96,11 @@
 			return can_edit_extender($this->id,$this->type,$user_guid);

 		}

 		
+		/**
+		 * Export this object
+		 *
+		 * @return array
+		 */
 		public function export()
 		{
 			$tmp = new stdClass;
@@ -89,6 +110,14 @@
 			return $tmp;
 		}
 		
+		/**
+		 * Import an object
+		 *
+		 * @param array $data
+		 * @param int $version
+		 * @return ElggExtender
+		 * @throws ImportException
+		 */
 		public function import(array $data, $version = 1)
 		{
 			if ($version == 1)
diff --git a/engine/lib/metadata.php b/engine/lib/metadata.php
index 41ab51ac1..65b2a9d40 100644
--- a/engine/lib/metadata.php
+++ b/engine/lib/metadata.php
@@ -12,9 +12,12 @@
 	 */
 
 	/**
-	 * @class ElggMetadata
+	 * ElggMetadata
 	 * This class describes metadata that can be attached to ElggEntities.
+	 * 
 	 * @author Marcus Povey <marcus@dushka.co.uk>
+	 * @package Elgg
+	 * @subpackage Core
 	 */
 	class ElggMetadata extends ElggExtender
 	{
@@ -45,14 +48,32 @@
 			}
 		}
 		
+		/**
+		 * Class member get overloading
+		 *
+		 * @param string $name
+		 * @return mixed
+		 */
 		function __get($name) {
 			return $this->get($name);
 		}
 		
+		/**
+		 * Class member set overloading
+		 *
+		 * @param string $name
+		 * @param mixed $value
+		 * @return mixed
+		 */
 		function __set($name, $value) {
 			return $this->set($name, $value);
 		}		
 		
+		/**
+		 * Save matadata object
+		 *
+		 * @return int the metadata object id
+		 */
 		function save()
 		{
 			if ($this->id > 0)
diff --git a/engine/lib/objects.php b/engine/lib/objects.php
index 2ef9cd284..29f29955a 100644
--- a/engine/lib/objects.php
+++ b/engine/lib/objects.php
@@ -13,8 +13,11 @@
 	 */

 

 	/**

-	 * @class ElggObject

-	 * Representation of an "object" in the system.

+	 * ElggObject

+	 * Representation of an "object" in the system.
+	 * 
+	 * @package Elgg
+	 * @subpackage Core

 	 */

 	class ElggObject extends ElggEntity

 	{

@@ -72,8 +75,22 @@
 				}

 			}

 		}

-		

-		function __get($name) { return $this->get($name); }

+		
+		/**
+		 * Class member get overloading
+		 *
+		 * @param string $name
+		 * @return mixed
+		 */

+		function __get($name) { return $this->get($name); }
+		
+		/**
+		 * Class member set overloading
+		 *
+		 * @param string $name
+		 * @param mixed $value
+		 * @return mixed
+		 */

 		function __set($name, $value) { return $this->set($name, $value); }

 		

 		/**

diff --git a/engine/lib/plugins.php b/engine/lib/plugins.php
index 868772ec7..e5b292492 100644
--- a/engine/lib/plugins.php
+++ b/engine/lib/plugins.php
@@ -16,7 +16,9 @@
 	/**

 	 * For now, loads plugins directly

 	 *

-	 * @todo Add proper plugin handler that launches plugins in an admin-defined order and activates them on admin request

+	 * @todo Add proper plugin handler that launches plugins in an admin-defined order and activates them on admin request
+	 * @package Elgg
+	 * @subpackage Core

 	 */

 		function load_plugins() {

 

@@ -43,8 +45,12 @@
 		}

 		

 	/**

-	 * @class PluginException 

-	 * A plugin Exception, thrown when an Exception occurs relating to the plugin mechanism. Subclass for specific plugin Exceptions.

+	 * PluginException
+	 *  

+	 * A plugin Exception, thrown when an Exception occurs relating to the plugin mechanism. Subclass for specific plugin Exceptions.
+	 * 
+	 * @package Elgg
+	 * @subpackage Exceptions

 	 */

 		

 		class PluginException extends Exception {}

diff --git a/engine/lib/relationships.php b/engine/lib/relationships.php
index 4214c1522..52418e500 100644
--- a/engine/lib/relationships.php
+++ b/engine/lib/relationships.php
@@ -13,8 +13,10 @@
 
 	/**
 	 * Relationship class.
-	 * @class ElggRelationship
+	 * 
 	 * @author Marcus Povey
+	 * @package Elgg
+	 * @subpackage Core
 	 */
 	class ElggRelationship implements Importable, Exportable
 	{
@@ -49,6 +51,12 @@
 			}
 		}
 		
+		/**
+		 * Class member get overloading
+		 *
+		 * @param string $name
+		 * @return mixed
+		 */
 		protected function __get($name) {
 			if (isset($this->attributes[$name])) 
 				return $this->attributes[$name];
@@ -56,11 +64,23 @@
 			return null;
 		}
 		
+		/**
+		 * Class member set overloading
+		 *
+		 * @param string $name
+		 * @param mixed $value
+		 * @return mixed
+		 */
 		protected function __set($name, $value) {
 			$this->attributes[$name] = $value;
 			return true;
 		}
 
+		/**
+		 * Save the relationship
+		 *
+		 * @return int the relationship id
+		 */
 		public function save()
 		{
 			if ($this->id > 0)
@@ -84,6 +104,11 @@
 		}
 	
 	
+		/**
+		 * Export this relationship
+		 *
+		 * @return array
+		 */
 		public function export()
 		{
 			$tmp = new stdClass;
@@ -93,6 +118,14 @@
 			return $tmp;
 		}
 		
+		/**
+		 * Import a relationship
+		 *
+		 * @param array $data
+		 * @param int $version
+		 * @return ElggRelationship
+		 * @throws ImportException
+		 */
 		public function import(array $data, $version = 1)
 		{
 			if ($version == 1)
diff --git a/engine/lib/sites.php b/engine/lib/sites.php
index fa49d26fc..a0d5005ee 100644
--- a/engine/lib/sites.php
+++ b/engine/lib/sites.php
@@ -85,7 +85,7 @@
 		}
 		
 		/**
-		 * Class variable getter overloading
+		 * Class member get overloading
 		 *
 		 * @param string $name
 		 * @return mixed
@@ -93,7 +93,7 @@
 		function __get($name) { return $this->get($name); }
 		
 		/**
-		 * Class variable setter overloading
+		 * Class member set overloading
 		 *
 		 * @param string $name
 		 * @param mixed $value
diff --git a/engine/lib/users.php b/engine/lib/users.php
index 2b4f89704..cdd7f9a3d 100644
--- a/engine/lib/users.php
+++ b/engine/lib/users.php
@@ -90,7 +90,7 @@
 		}

 		
 		/**
-		 * Class variable getter overloading
+		 * Class member get overloading
 		 *
 		 * @param string $name
 		 * @return mixed
@@ -98,7 +98,7 @@
 		function __get($name) { return $this->get($name); }
 		
 		/**
-		 * Class variable setter overloading
+		 * Class member set overloading
 		 *
 		 * @param string $name
 		 * @param mixed $value