Refs #2450: Documented first bit of the classes.

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

14 files changed, 198 insertions, 78 deletions

diff --git a/engine/classes/APIException.php b/engine/classes/APIException.php
index d6eb9ce52..6ce9424d8 100644
--- a/engine/classes/APIException.php
+++ b/engine/classes/APIException.php
@@ -1,10 +1,10 @@
 <?php

 /**

- * APIException

- * The API Exception class, thrown by the API layer when an API call has an issue.

+ * API Exception Stub

  *

- * @author Curverider Ltd <info@elgg.com>

- * @package Elgg

- * @subpackage Exceptions

+ * Generic parent class for API exceptions.

+ *

+ * @package Elgg.Core

+ * @subpackage Exceptions.Stub

  */

-class APIException extends Exception {}

+class APIException extends Exception {}
\ No newline at end of file
diff --git a/engine/classes/AccessControlQueryComponent.php b/engine/classes/AccessControlQueryComponent.php
index ad5410ddc..7808800bc 100644
--- a/engine/classes/AccessControlQueryComponent.php
+++ b/engine/classes/AccessControlQueryComponent.php
@@ -1,12 +1,13 @@
 <?php

 /**

- * @class AccessControlQueryComponent

- * Access control component.

- * @author Curverider Ltd

- * @see Query

+ * The access control component of the query class.

+ *

+ * @todo probably remove.

+ * @access private

+ * @package Elgg.Core

+ * @subpackage Unimplemented

  */

-class AccessControlQueryComponent extends QueryComponent

-{

+class AccessControlQueryComponent extends QueryComponent {

 	/**

 	 * Construct the ACL.

 	 *

@@ -15,8 +16,7 @@ class AccessControlQueryComponent extends QueryComponent
 	 * @param string $object_owner_table The table containing the owner information for the stuff you're retrieving.

 	 * @param string $object_owner_id_field The field in $object_owner_table containing the owner information

 	 */

-	function __construct($acl_table = "entities", $acl_field = "access_id", $object_owner_table = "entities", $object_owner_id_field = "owner_guid")

-	{

+	function __construct($acl_table = "entities", $acl_field = "access_id", $object_owner_table = "entities", $object_owner_id_field = "owner_guid") {

 		global $CONFIG;

 

 		$this->acl_table = $CONFIG->dbprefix . sanitise_string($acl_table);

@@ -25,8 +25,7 @@ class AccessControlQueryComponent extends QueryComponent
 		$this->object_owner_id_field = sanitise_string($object_owner_id_field);

 	}

 

-	function __toString()

-	{

+	function __toString() {

 		//$access = get_access_list();

 		// KJ - changed to use get_access_sql_suffix

 		// Note: currently get_access_sql_suffix is hardwired to use

@@ -37,4 +36,4 @@ class AccessControlQueryComponent extends QueryComponent
 

 		//return "and ({$this->acl_table}.{$this->acl_field} in {$access} or ({$this->acl_table}.{$this->acl_field} = 0 and {$this->object_owner_table}.{$this->object_owner_id_field} = {$_SESSION['id']}))";

 	}

-}

+}
\ No newline at end of file
diff --git a/engine/classes/CallException.php b/engine/classes/CallException.php
index 369ce19bd..aaa55a653 100644
--- a/engine/classes/CallException.php
+++ b/engine/classes/CallException.php
@@ -1,10 +1,10 @@
 <?php

 /**

- * CallException

- * An exception thrown when there is a problem calling something.

+ * Call Exception Stub

  *

- * @author Curverider Ltd <info@elgg.com>

- * @package Elgg

- * @subpackage Exceptions

+ * Generic parent class for Call exceptions

+ *

+ * @package Elgg.Core

+ * @subpackage Exceptions.Stub

  */

-class CallException extends Exception {}

+class CallException extends Exception {}
\ No newline at end of file
diff --git a/engine/classes/ClassException.php b/engine/classes/ClassException.php
index 6dfb57b0e..50dd18d18 100644
--- a/engine/classes/ClassException.php
+++ b/engine/classes/ClassException.php
@@ -1,10 +1,10 @@
 <?php

 /**

- * ClassException

- * A class Exception, throw when there is a class error.

+ * Class Exception

  *

- * @author Curverider Ltd <info@elgg.com>

- * @package Elgg

- * @subpackage Exceptions

+ * A generic parent class for Class exceptions

+ *

+ * @package Elgg.Core

+ * @subpackage Exceptions.Stub

  */

 class ClassException extends Exception {}

diff --git a/engine/classes/ClassNotFoundException.php b/engine/classes/ClassNotFoundException.php
index f344e6b28..f35b2e40a 100644
--- a/engine/classes/ClassNotFoundException.php
+++ b/engine/classes/ClassNotFoundException.php
@@ -1,10 +1,10 @@
 <?php

 /**

- * ClassNotFoundException

- * An Class not found Exception, throw when an class can not be found occurs.

+ * Class not found

  *

- * @author Curverider Ltd <info@elgg.com>

- * @package Elgg

+ * Thrown when trying to load a class that doesn't exist.

+ *

+ * @package Elgg.Core

  * @subpackage Exceptions

  */

 class ClassNotFoundException extends ClassException {}
\ No newline at end of file
diff --git a/engine/classes/ConfigurationException.php b/engine/classes/ConfigurationException.php
index a3c7c38cc..adccdbc11 100644
--- a/engine/classes/ConfigurationException.php
+++ b/engine/classes/ConfigurationException.php
@@ -1,10 +1,10 @@
 <?php

 /**

- * ConfigurationException

- * There is a configuration error

+ * Configuration exception

+ *

+ * A generic parent class for Configuration exceptions

  *

- * @author Curverider Ltd <info@elgg.com>

  * @package Elgg

- * @subpackage Exceptions

+ * @subpackage Exceptions.Stub

  */

 class ConfigurationException extends Exception {}

diff --git a/engine/classes/CronException.php b/engine/classes/CronException.php
index 3720c2c59..440fa9481 100644
--- a/engine/classes/CronException.php
+++ b/engine/classes/CronException.php
@@ -1,3 +1,10 @@
 <?php

-/** The cron exception. */

+/**

+ * Cron exception

+ *

+ * A generic parent class for cron exceptions

+ *

+ * @package Elgg

+ * @subpackage Exceptions.Stub

+ */

 class CronException extends Exception {}
\ No newline at end of file
diff --git a/engine/classes/DataFormatException.php b/engine/classes/DataFormatException.php
index 2038f1fb7..be443efce 100644
--- a/engine/classes/DataFormatException.php
+++ b/engine/classes/DataFormatException.php
@@ -3,8 +3,7 @@
  * Data format exception

  * An exception thrown when there is a problem in the format of some data.

  *

- * @author Curverider Ltd <info@elgg.com>

- * @package Elgg

- * @subpackage Exceptions

+ * @package Elgg.Core

+ * @subpackage Exceptions.Stub

  */

 class DataFormatException extends Exception {}

diff --git a/engine/classes/DatabaseException.php b/engine/classes/DatabaseException.php
index ffc414abf..06ffd6782 100644
--- a/engine/classes/DatabaseException.php
+++ b/engine/classes/DatabaseException.php
@@ -1,10 +1,10 @@
 <?php

 /**

- * DatabaseException

- * An database exception, throw when a database exception happens, subclass if more detail is needed.

+ * Database Exception

  *

- * @author Curverider Ltd <info@elgg.com>

- * @package Elgg

- * @subpackage Exceptions

+ * A generic parent class for database exceptions

+ *

+ * @package Elgg.Core

+ * @subpackage Exceptions.Stub

  */

 class DatabaseException extends Exception {}

diff --git a/engine/classes/DeleteQueryTypeQueryComponent.php b/engine/classes/DeleteQueryTypeQueryComponent.php
index 645e95cb5..328c57b31 100644
--- a/engine/classes/DeleteQueryTypeQueryComponent.php
+++ b/engine/classes/DeleteQueryTypeQueryComponent.php
@@ -1,9 +1,11 @@
 <?php

 /**

- * @class DeleteQueryTypeQueryComponent

- * A delete query.

- * @author Curverider Ltd

- * @see Query

+ * Delete query

+ *

+ * @todo probably remove.

+ * @access private

+ * @package Elgg.Core

+ * @subpackage Unimplemented

  */

 class DeleteQueryTypeQueryComponent extends QueryTypeQueryComponent

 {

diff --git a/engine/classes/ElggAccess.php b/engine/classes/ElggAccess.php
index 57cceef03..fd511ca58 100644
--- a/engine/classes/ElggAccess.php
+++ b/engine/classes/ElggAccess.php
@@ -1,6 +1,12 @@
 <?php

 /**

- * Temporary class used to determing if access is being ignored

+ * Class used to determin if access is being ignored.

+ *

+ * @access private

+ * @todo I don't remember why this was required beyond scope concerns.

+ * @see elgg_get_ignore_access()

+ * @package Elgg.Core

+ * @subpackage Access

  */

 class ElggAccess {

 	/**

diff --git a/engine/classes/ElggAnnotation.php b/engine/classes/ElggAnnotation.php
index fe85ca082..0275663dc 100644
--- a/engine/classes/ElggAnnotation.php
+++ b/engine/classes/ElggAnnotation.php
@@ -1,13 +1,14 @@
 <?php

 /**

- * ElggAnnotation

+ * Elgg Annotations

  *

- * An annotation is similar to metadata.

- * Each entity can have more than one of each type of annotation.

+ * Annotations allow you to attach bits of information to entities.

+ * They are essentially the same as metadata, but with additional

+ * helper functions.

  *

- * @package Elgg

- * @subpackage Core

- * @author Curverider Ltd <info@elgg.com>

+ * @package Elgg.Core

+ * @subpackage DataModel.Annotations

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

  */

 class ElggAnnotation extends ElggExtender {

 

diff --git a/engine/classes/ElggCache.php b/engine/classes/ElggCache.php
index c59285467..f10b6d9ea 100644
--- a/engine/classes/ElggCache.php
+++ b/engine/classes/ElggCache.php
@@ -1,12 +1,10 @@
 <?php

-

 /**

  * ElggCache The elgg cache superclass.

  * This defines the interface for a cache (wherever that cache is stored).

  *

- * @author Curverider Ltd <info@elgg.com>

- * @package Elgg

- * @subpackage API

+ * @package Elgg.Core

+ * @subpackage Cache

  */

 abstract class ElggCache implements

 	// Override for array access

diff --git a/engine/classes/ElggDiskFilestore.php b/engine/classes/ElggDiskFilestore.php
index 6b0fa2554..b0924fbe7 100644
--- a/engine/classes/ElggDiskFilestore.php
+++ b/engine/classes/ElggDiskFilestore.php
@@ -1,8 +1,13 @@
 <?php
 /**
- * @class ElggDiskFilestore
- * This class uses disk storage to save data.
- * @author Curverider Ltd
+ * A filestore that uses disk as storage.
+ *
+ * @warning This should be used by a wrapper class
+ * like {@link ElggFile}.
+ *
+ * @package Elgg.Core
+ * @subpackage FileStore.Disk
+ * @link http://docs.elgg.org/DataModel/FileStore/Disk
  */
 class ElggDiskFilestore extends ElggFilestore {
 	/**
@@ -30,6 +35,19 @@ class ElggDiskFilestore extends ElggFilestore {
 		}
 	}
 
+	/**
+	 * Open a file for reading, writing, or both.
+	 *
+	 * @note All files are opened binary safe.
+	 * @warning This will try to create the a directory if it doesn't exist,
+	 * even in read-only mode.
+	 *
+	 * @param ElggFile $file
+	 * @param string $mode read, write, or append.
+	 * @throws InvalidParameterException
+	 * @return resource File pointer resource
+	 * @todo This really shouldn't try to create directories if not writing.
+	 */
 	public function open(ElggFile $file, $mode) {
 		$fullname = $this->getFilenameOnFilestore($file);
 
@@ -71,10 +89,25 @@ class ElggDiskFilestore extends ElggFilestore {
 
 	}
 
+	/**
+	 * Write data to a file.
+	 *
+	 * @param resource $f File pointer resource
+	 * @param mixed $data The data to write.
+	 * @return bool
+	 */
 	public function write($f, $data) {
 		return fwrite($f, $data);
 	}
 
+	/**
+	 * Read data from a file.
+	 *
+	 * @param resource $f File pointer resource
+	 * @param int $length The number of bytes to read
+	 * @param inf $offset The number of bytes to start after
+	 * @return mixed Contents of file or false on fail.
+	 */
 	public function read($f, $length, $offset = 0) {
 		if ($offset) {
 			$this->seek($f, $offset);
@@ -83,10 +116,22 @@ class ElggDiskFilestore extends ElggFilestore {
 		return fread($f, $length);
 	}
 
+	/**
+	 * Close a file pointer
+	 *
+	 * @param resource $f A file pointer resource
+	 * @return bool
+	 */
 	public function close($f) {
 		return fclose($f);
 	}
 
+	/**
+	 * Delete an ElggFile file.
+	 *
+	 * @param ElggFile $file File to delete
+	 * @return bool
+	 */
 	public function delete(ElggFile $file) {
 		$filename = $this->getFilenameOnFilestore($file);
 		if (file_exists($filename)) {
@@ -96,22 +141,49 @@ class ElggDiskFilestore extends ElggFilestore {
 		}
 	}
 
+	/**
+	 * Seek to the specified position.
+	 *
+	 * @param resource $f File resource
+	 * @param int $position Position in bytes
+	 */
 	public function seek($f, $position) {
 		return fseek($f, $position);
 	}
 
+	/**
+	 * Return the current location of the internal pointer
+	 *
+	 * @param resource $f File pointer resource
+	 */
 	public function tell($f) {
 		return ftell($f);
 	}
 
+	/**
+	 * Tests for end of file on a file pointer
+	 * @param resource $f File pointer resource
+	 */
 	public function eof($f) {
 		return feof($f);
 	}
 
+	/**
+	 * Returns the file size of an ElggFile file.
+	 *
+	 * @param ElggFile $file
+	 * @return int The file size
+	 */
 	public function getFileSize(ElggFile $file) {
 		return filesize($this->getFilenameOnFilestore($file));
 	}
 
+	/**
+	 * Returns the filename as saved on disk for an ElggFile object
+	 *
+	 * @param ElggFile $file
+	 * @return string The full path of where the file is stored
+	 */
 	public function getFilenameOnFilestore(ElggFile $file) {
 		$owner = $file->getOwnerEntity();
 		if (!$owner) {
@@ -125,26 +197,47 @@ class ElggDiskFilestore extends ElggFilestore {
 		return $this->dir_root . $this->make_file_matrix($owner->guid) . $file->getFilename();
 	}
 
+	/**
+	 * Returns the contents of the ElggFile file.
+	 *
+	 * @param ElggFile $file
+	 * @return mixed
+	 */
 	public function grabFile(ElggFile $file) {
 		return file_get_contents($file->getFilenameOnFilestore());
 	}
 
+	/**
+	 * Tests if an ElggFile file exists.
+	 *
+	 * @param ElggFile $file
+	 * @return bool
+	 */
 	public function exists(ElggFile $file) {
 		return file_exists($this->getFilenameOnFilestore($file));
 	}
 
-	public function getSize($prefix,$container_guid) {
+	/**
+	 * Returns the size of all data stored under a directory in the disk store.
+	 *
+	 * @param string $prefix Optional/ The prefix to check under.
+	 * @param string $container_guid The guid of the entity whose data you want to check.
+	 * @return int|false
+	 */
+	public function getSize($prefix = '', $container_guid) {
 		if ($container_guid) {
-			return get_dir_size($this->dir_root.$this->make_file_matrix($container_guid).$prefix);
+			return get_dir_size($this->dir_root . $this->make_file_matrix($container_guid) . $prefix);
 		} else {
 			return false;
 		}
 	}
 
 	/**
-	 * Make the directory root.
+	 * Create a directory $dirroot
 	 *
-	 * @param string $dirroot
+	 * @param string $dirroot The full path of the directory to create
+	 * @throws IOException
+	 * @return true
 	 */
 	protected function make_directory_root($dirroot) {
 		if (!file_exists($dirroot)) {
@@ -165,6 +258,7 @@ class ElggDiskFilestore extends ElggFilestore {
 	 * @param string $string String
 	 * @param string $charset The charset, defaults to UTF8
 	 * @return array
+	 * @todo Can be deprecated since we no long split on usernames
 	 */
 	private function mb_str_split($string, $charset = 'UTF8') {
 		if (is_callable('mb_substr')) {
@@ -187,10 +281,10 @@ class ElggDiskFilestore extends ElggFilestore {
 	}
 
 	/**
-	 * Construct the filename matrix.
+	 * Construct a file path matrix for an entity.
 	 *
-	 * @param int | string $identifier
-	 * @return str
+	 * @param int The guide of the entity to store the data under.
+	 * @return str The path where the entity's data will be stored.
 	 */
 	protected function make_file_matrix($identifier) {
 		if (is_numeric($identifier)) {
@@ -201,19 +295,22 @@ class ElggDiskFilestore extends ElggFilestore {
 	}
 
 	/**
-	 * Construct the filename matrix with user info
+	 * Construct a filename matrix.
 	 *
-	 * This method will generate a matrix using the entity's creation time and
-	 * unique guid. This is intended only to determine a user's data directory.
+	 * Generates a matrix using the entity's creation time and
+	 * unique guid.
 	 *
-	 * @param int $guid
-	 * @return str
+	 * File path matrixes are:
+	 * YYYY/MM/DD/guid/
+	 *
+	 * @param int $guid The entity to contrust a matrix for
+	 * @return str The
+	 * @todo This would work with non-users.  Why is it restricted to only users?
 	 */
 	protected function user_file_matrix($guid) {
 		// lookup the entity
 		$user = get_entity($guid);
-		if ($user->type != 'user')
-		{
+		if ($user->type != 'user') {
 			// only to be used for user directories
 			return FALSE;
 		}
@@ -248,10 +345,21 @@ class ElggDiskFilestore extends ElggFilestore {
 		return $this->user_file_matrix($user->guid);
 	}
 
+	/**
+	 * Returns a list of attributes to save to the database when saving
+	 * the ElggFile object using this file store.
+	 *
+	 * @return array
+	 */
 	public function getParameters() {
 		return array("dir_root" => $this->dir_root);
 	}
 
+	/**
+	 * Sets parameters that should be saved to database.
+	 *
+	 * return bool
+	 */
 	public function setParameters(array $parameters) {
 		if (isset($parameters['dir_root'])) {
 			$this->dir_root = $parameters['dir_root'];
@@ -260,4 +368,4 @@ class ElggDiskFilestore extends ElggFilestore {
 
 		return false;
 	}
-}
+}
\ No newline at end of file