Refs #2450: Documented a few more classes.

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

4 files changed, 68 insertions, 29 deletions

diff --git a/engine/classes/ElggAnnotation.php b/engine/classes/ElggAnnotation.php
index 0275663dc..709e28433 100644
--- a/engine/classes/ElggAnnotation.php
+++ b/engine/classes/ElggAnnotation.php
@@ -6,6 +6,8 @@
  * They are essentially the same as metadata, but with additional

  * helper functions.

  *

+ * @internal Annotations are stored in the annotations table.

+ *

  * @package Elgg.Core

  * @subpackage DataModel.Annotations

  * @link http://docs.elgg.org/DataModel/Annotations

diff --git a/engine/classes/ElggExtender.php b/engine/classes/ElggExtender.php
index ec7a21f35..1a544b9a9 100644
--- a/engine/classes/ElggExtender.php
+++ b/engine/classes/ElggExtender.php
@@ -1,11 +1,21 @@
 <?php

-

 /**

- * ElggExtender

+ * The base class for ElggEntity extenders.

+ *

+ * Extenders allow you to attach extended information to an

+ * ElggEntity.  Core supports two: ElggAnnotation, ElggMetadata,

+ * and ElggRelationship

+ *

+ * Saving the extender data to database is handled by the child class.

+ *

+ * @tip Plugin authors would probably want to extend either ElggAnnotation

+ * or ElggMetadata instead of this class.

  *

- * @author Curverider Ltd

- * @package Elgg

- * @subpackage Core

+ * @package Elgg.Core

+ * @subpackage DataModel.Extender

+ * @see ElggAnnotation

+ * @see ElggMetadata

+ * @link http://docs.elgg.org/DataModel/Extenders

  */

 abstract class ElggExtender implements

 	Exportable,

@@ -14,13 +24,14 @@ abstract class ElggExtender implements
 	ArrayAccess // Override for array access

 {

 	/**

-	 * This contains the site's main properties (id, etc)

+	 * Holds attributes to save to database

+	 *

 	 * @var array

 	 */

 	protected $attributes;

 

 	/**

-	 * Get an attribute

+	 * Returns an attribute

 	 *

 	 * @param string $name

 	 * @return mixed

@@ -66,18 +77,18 @@ abstract class ElggExtender implements
 	}

 

 	/**

-	 * Return the owner of this annotation.

+	 * Return the owner guid of this extender.

 	 *

-	 * @return mixed

+	 * @return int

 	 */

 	public function getOwner() {

 		return $this->owner_guid;

 	}

 

 	/**

-	 * Return the owner entity

+	 * Return the owner entity.

 	 *

-	 * @return mixed

+	 * @return ElggEntity|false

 	 * @since 1.7.0

 	 */

 	public function getOwnerEntity() {

@@ -85,7 +96,7 @@ abstract class ElggExtender implements
 	}

 

 	/**

-	 * Returns the entity this is attached to

+	 * Return the entity this describes.

 	 *

 	 * @return ElggEntity The enttiy

 	 */

@@ -104,10 +115,10 @@ abstract class ElggExtender implements
 	abstract public function delete();

 

 	/**

-	 * Determines whether or not the specified user can edit this

+	 * Returns if a user can edit this extended data.

 	 *

 	 * @param int $user_guid The GUID of the user (defaults to currently logged in user)

-	 * @return true|false

+	 * @return bool

 	 */

 	public function canEdit($user_guid = 0) {

 		return can_edit_extender($this->id,$this->type,$user_guid);

@@ -120,10 +131,14 @@ abstract class ElggExtender implements
 	 */

 	public abstract function getURL();

 

-	// EXPORTABLE INTERFACE ////////////////////////////////////////////////////////////

+	/*

+	 * EXPORTABLE INTERFACE

+	 */

 

 	/**

 	 * Return an array of fields which can be exported.

+	 *

+	 * @return array

 	 */

 	public function getExportableValues() {

 		return array(

@@ -151,7 +166,9 @@ abstract class ElggExtender implements
 		return $meta;

 	}

 

-	// SYSTEM LOG INTERFACE ////////////////////////////////////////////////////////////

+	/*

+	 * SYSTEM LOG INTERFACE

+	 */

 

 	/**

 	 * Return an identification for the object for storage in the system log.

@@ -165,6 +182,8 @@ abstract class ElggExtender implements
 

 	/**

 	 * Return the class name of the object.

+	 *

+	 * @return string

 	 */

 	public function getClassName() {

 		return get_class($this);

@@ -172,13 +191,17 @@ abstract class ElggExtender implements
 

 	/**

 	 * Return the GUID of the owner of this object.

+	 *

+	 * @return int

 	 */

 	public function getObjectOwnerGUID() {

 		return $this->owner_guid;

 	}

 

 	/**

-	 * Return a type of the object - eg. object, group, user, relationship, metadata, annotation etc

+	 * Return a type of extension.

+	 *

+	 * @return string

 	 */

 	public function getType() {

 		return $this->type;

@@ -187,18 +210,22 @@ abstract class ElggExtender implements
 	/**

 	 * Return a subtype. For metadata & annotations this is the 'name' and

 	 * for relationship this is the relationship type.

+	 *

+	 * @return string

 	 */

 	public function getSubtype() {

 		return $this->name;

 	}

 

 

-	// ITERATOR INTERFACE //////////////////////////////////////////////////////////////

+	/*

+	 * ITERATOR INTERFACE

+	 */

+

 	/*

 	 * This lets an entity's attributes be displayed using foreach as a normal array.

 	 * Example: http://www.sitepoint.com/print/php5-standard-library

 	 */

-

 	private $valid = FALSE;

 

 	function rewind() {

@@ -221,12 +248,14 @@ abstract class ElggExtender implements
 		return $this->valid;

 	}

 

-	// ARRAY ACCESS INTERFACE //////////////////////////////////////////////////////////

+	/*

+	 * ARRAY ACCESS INTERFACE

+	 */

+

 	/*

 	 * This lets an entity's attributes be accessed like an associative array.

 	 * Example: http://www.sitepoint.com/print/php5-standard-library

 	 */

-

 	function offsetSet($key, $value) {

 		if ( array_key_exists($key, $this->attributes) ) {

 			$this->attributes[$key] = $value;

diff --git a/engine/classes/ElggPlugin.php b/engine/classes/ElggPlugin.php
index 921665f4d..c666b8438 100644
--- a/engine/classes/ElggPlugin.php
+++ b/engine/classes/ElggPlugin.php
@@ -1,8 +1,12 @@
 <?php

 /**

- * @class ElggPlugin Object representing a plugin's settings for a given site.

- * This class is currently a stub, allowing a plugin to saving settings in an object's metadata for each site.

- * @author Curverider Ltd

+ * Stores site-side plugin settings as private data.

+ *

+ * This class is currently a stub, allowing a plugin to

+ * save settings in an object's private settings for each site.

+ *

+ * @package Elgg.Core

+ * @subpackage Plugins.Settings

  */

 class ElggPlugin extends ElggObject {

 	protected function initialise_attributes() {

@@ -16,7 +20,10 @@ class ElggPlugin extends ElggObject {
 	}

 

 	/**

-	 * Override entity get and sets in order to save data to private data store.

+	 * Get a value from private settings.

+	 *

+	 * @param string $name

+	 * @return mixed

 	 */

 	public function get($name) {

 		// See if its in our base attribute

@@ -37,7 +44,10 @@ class ElggPlugin extends ElggObject {
 	}

 

 	/**

-	 * Override entity get and sets in order to save data to private data store.

+	 * Save a value to private settings.

+	 *

+	 * @param string $name

+	 * @param mixed $value

 	 */

 	public function set($name, $value) {

 		if (array_key_exists($name, $this->attributes)) {

diff --git a/engine/classes/ElggRelationship.php b/engine/classes/ElggRelationship.php
index 4d14941a9..e7574eb3b 100644
--- a/engine/classes/ElggRelationship.php
+++ b/engine/classes/ElggRelationship.php
@@ -1,10 +1,8 @@
 <?php

-

 /**

  * Relationship class.

  *

- * @author Curverider Ltd

- * @package Elgg

+ * @package Elgg.Core

  * @subpackage Core

  */

 class ElggRelationship implements