From c9cd07139c6be349d5185cbbbe022fff94dc1cd3 Mon Sep 17 00:00:00 2001
From: "mariano.iglesias"
 <mariano.iglesias@3807eeeb-6ff5-0310-8944-8be069107fe0>
Date: Sat, 26 May 2007 19:33:55 +0000
Subject: [PATCH] Adding documentation for Socket, Validation and Xml

git-svn-id: https://svn.cakephp.org/repo/branches/1.2.x.x@5201 3807eeeb-6ff5-0310-8944-8be069107fe0
---
 cake/libs/socket.php     |  53 +++++++-----
 cake/libs/validation.php | 176 ++++++++++++++++++++++++++++++++-------
 cake/libs/xml.php        | 121 ++++++++++++++++++---------
 3 files changed, 261 insertions(+), 89 deletions(-)

diff --git a/cake/libs/socket.php b/cake/libs/socket.php
index 7204b2a1a..35dfd3bf8 100644
--- a/cake/libs/socket.php
+++ b/cake/libs/socket.php
@@ -39,12 +39,14 @@ class CakeSocket extends Object {
  * Object description
  *
  * @var string
+ * @access public
  */
 	var $description = 'Remote DataSource Network Socket Interface';
 /**
  * Base configuration settings for the socket connection
  *
  * @var array
+ * @access protected
  */
 	var $_baseConfig = array(
 		'persistent'	=> false,
@@ -57,29 +59,33 @@ class CakeSocket extends Object {
  * Configuration settings for the socket connection
  *
  * @var array
+ * @access public
  */
 	var $config = array();
 /**
  * Reference to socket connection resource
  *
  * @var resource
+ * @access public
  */
 	var $connection = null;
-	
+
 /**
  * This boolean contains the current state of the CakeSocket class
  *
  * @var boolean
+ * @access public
  */
 	var $connected = false;
-	
+
 /**
  * This variable contains an array with the last error number (num) and string (str)
  *
  * @var array
+ * @access public
  */
 	var $error = array();
-		
+
 /**
  * Constructor.
  *
@@ -87,12 +93,12 @@ class CakeSocket extends Object {
  */
 	function __construct($config = array()) {
 		parent::__construct();
-		
+
 		$classVars = get_class_vars(__CLASS__);
 		$baseConfig = $classVars['_baseConfig'];
-		
+
 		$this->config = am($baseConfig, $config);
-		
+
 		if (!is_numeric($this->config['protocol'])) {
 			$this->config['protocol'] = getprotobyname($this->config['protocol']);
 		}
@@ -101,6 +107,7 @@ class CakeSocket extends Object {
  * Connect the socket to the given host and port.
  *
  * @return boolean Success
+ * @access public
  */
 	function connect() {
 		if ($this->connection != null) {
@@ -108,25 +115,26 @@ class CakeSocket extends Object {
 		}
 
 		if ($this->config['persistent'] == true) {
-			$tmp = null;			
+			$tmp = null;
 			$this->connection = @pfsockopen($this->config['host'], $this->config['port'], $errNum, $errStr, $this->config['timeout']);
 		} else {
 			$this->connection = fsockopen($this->config['host'], $this->config['port'], $errNum, $errStr, $this->config['timeout']);
 		}
-		
+
 		if (!empty($errNum) || !empty($errStr)) {
 			$this->setLastError($errStr, $errNum);
 		}
-		
+
 		$this->connected = is_resource($this->connection);
-		
+
 		return $this->connected;
 	}
-		
+
 /**
  * Get the host name of the current connection.
  *
  * @return string Host name
+ * @access public
  */
 	function host() {
 		if (Validation::ip($this->config['host'])) {
@@ -139,6 +147,7 @@ class CakeSocket extends Object {
  * Get the IP address of the current connection.
  *
  * @return string IP address
+ * @access public
  */
 	function address() {
 		if (Validation::ip($this->config['host'])) {
@@ -151,6 +160,7 @@ class CakeSocket extends Object {
  * Get all IP addresses associated with the current connection.
  *
  * @return array IP addresses
+ * @access public
  */
 	function addresses() {
 		if (Validation::ip($this->config['host'])) {
@@ -162,7 +172,8 @@ class CakeSocket extends Object {
 /**
  * Get the last error as a string.
  *
- * @return string
+ * @return string Last error
+ * @access public
  */
 	function lastError() {
 		if (!empty($this->error)) {
@@ -176,7 +187,7 @@ class CakeSocket extends Object {
  *
  * @param int $errNum Error code
  * @param string $errStr Error string
- * @return void
+ * @access public
  */
 	function setLastError($errNum, $errStr) {
 		$this->lastError = array('num' => $errNum, 'str' => $errStr);
@@ -185,7 +196,8 @@ class CakeSocket extends Object {
  * Write data to the socket.
  *
  * @param string $data The data to write to the socket
- * @return boolean success
+ * @return boolean Success
+ * @access public
  */
 	function write($data) {
 		if (!$this->connected) {
@@ -193,16 +205,17 @@ class CakeSocket extends Object {
 				return false;
 			}
 		}
-		
+
 		return fwrite($this->connection, $data, strlen($data));
 	}
-	
+
 /**
  * Read data from the socket. Returns false if no data is available or no connection could be
  * established.
  *
  * @param int $length Optional buffer length to read; defaults to 1024
  * @return mixed Socket data
+ * @access public
  */
 	function read($length = 1024) {
 		if (!$this->connected) {
@@ -210,7 +223,7 @@ class CakeSocket extends Object {
 				return false;
 			}
 		}
-		
+
 		if (!feof($this->connection)) {
 			return fread($this->connection, $length);
 		} else {
@@ -221,6 +234,7 @@ class CakeSocket extends Object {
  * Abort socket operation.
  *
  * @return boolean Success
+ * @access public
  */
 	function abort() {
 	}
@@ -228,6 +242,7 @@ class CakeSocket extends Object {
  * Disconnect the socket from the current connection.
  *
  * @return boolean Success
+ * @access public
  */
 	function disconnect() {
 		if (!is_resource($this->connection)) {
@@ -242,9 +257,9 @@ class CakeSocket extends Object {
 		return !$this->connected;
 	}
 /**
- * Destruct.
+ * Destructor, used to disconnect from current connection.
  *
- * @return void
+ * @access private
  */
  	function __destruct() {
  		$this->disconnect();
diff --git a/cake/libs/validation.php b/cake/libs/validation.php
index 558f35420..34c638e68 100644
--- a/cake/libs/validation.php
+++ b/cake/libs/validation.php
@@ -46,7 +46,7 @@
  */
 	define('VALID_YEAR', '/^[12][0-9]{3}$/');
 /**
- * Short description for file.
+ * Offers different validation methods.
  *
  * Long description for file
  *
@@ -59,6 +59,7 @@ class Validation extends Object {
  * Set the the value of methods $check param.
  *
  * @var string
+ * @access public
  */
 	var $check = null;
 /**
@@ -66,6 +67,7 @@ class Validation extends Object {
  * Can be set from $regex param also
  *
  * @var string
+ * @access public
  */
 	var $regex = null;
 /**
@@ -73,18 +75,21 @@ class Validation extends Object {
  * This can be passed to methods in the $country param
  *
  * @var string
+ * @access public
  */
 	var $country = null;
 /**
  * Some class methods use a deeper validation when set to true
  *
  * @var string
+ * @access public
  */
  	var $deep = null;
 /**
  * Some class methods use the $type param to determine which validation to perfom in the method
  *
  * @var string
+ * @access public
  */
 	var $type = null;
 /**
@@ -92,6 +97,7 @@ class Validation extends Object {
  * These are used for debugging purposes
  *
  * @var array
+ * @access public
  */
 	var $errors = array();
 /**
@@ -108,8 +114,8 @@ class Validation extends Object {
  * $check can be passed as an array:
  * array('check' => 'valueToCheck');
  *
- * @param mixed $check
- * @return boolean
+ * @param mixed $check Value to check
+ * @return boolean Success
  * @access public
  */
 	function alphaNumeric($check) {
@@ -132,15 +138,14 @@ class Validation extends Object {
 		}
 	}
 /**
- * Checks that a string is within s specified range.
-
- * Spaces are included in the character count
+ * Checks that a string length is within s specified range.
+ * Spaces are included in the character count.
  * Returns true is string matches value min, max, or between min and max,
  *
- * @param string $check
- * @param int $min
- * @param int $max
- * @return boolean
+ * @param string $check Value to check for length
+ * @param int $min Minimum value in range (inclusive)
+ * @param int $max Maximum value in range (inclusive)
+ * @return boolean Success
  * @access public
  */
 	function between($check, $min, $max) {
@@ -159,8 +164,8 @@ class Validation extends Object {
  * $check can be passed as an array:
  * array('check' => 'valueToCheck');
  *
- * @param mixed $check
- * @return boolean
+ * @param mixed $check Value to check
+ * @return boolean Success
  * @access public
  */
 	function blank($check) {
@@ -179,19 +184,18 @@ class Validation extends Object {
 		}
 	}
 /**
- * Validation of credit card numbers
- *
- * Returns true if $check is in the proper credit card format
+ * Validation of credit card numbers.
+ * Returns true if $check is in the proper credit card format.
  *
  * @param mixed $check credit card number to validate
  * @param mixed $type 'all' may be passed as a sting, defaults to fast which checks format of most major credit cards
  * 							if an array is used only the values of the array are checked.
  * 							Example: array('amex', 'bankcard', 'maestro')
  * @param boolean $deep set to true this will check the Luhn algorithm of the credit card.
- * @see Validation::_luhn()
  * @param string $regex A custom regex can also be passed, this will be used instead of the defined regex values
- * @return boolean
+ * @return boolean Success
  * @access public
+ * @see Validation::_luhn()
  */
 	function cc($check, $type = 'fast', $deep = false, $regex = null) {
 		$this->__reset();
@@ -259,14 +263,13 @@ class Validation extends Object {
 		}
 	}
 /**
- * Used to compare 2 numeric values
+ * Used to compare 2 numeric values.
  *
  * @param mixed $check1 if string is passed for a string must also be passed for $check2
  * 							used as an array it must be passed as array('check1' => value, 'operator' => 'value', 'check2' -> value)
  * @param string $operator Can be either a word or operand
  * 								is greater >, is less <, greater or equal >=
  * 								less or equal <=, is less <, equal to ==, not equal !=
- *
  * @param int $check2 only needed if $check1 is a string
  * @return boolean
  * @access public
@@ -328,7 +331,7 @@ class Validation extends Object {
  * @param mixed $check When used as a string, $regex must also be a valid regular expression.
  *								As and array: array('check' => value, 'regex' => 'valid regular expression')
  * @param string $regex If $check is passed as a string, $regex must also be set to valid regular expression
- * @return boolean
+ * @return boolean Success
  * @access public
  */
 	function custom($check, $regex = null) {
@@ -358,7 +361,7 @@ class Validation extends Object {
  * 							My December 2006 or Dec 2006
  * 							my 12/2006 or 12/06 separators can be a space, period, dash, forward slash
  * @param string $regex If a custom regular expression is used this is the only validation that will occur.
- * @return boolean
+ * @return boolean Success
  * @access public
  */
 	function date($check, $format = 'ymd', $regex = null) {
@@ -403,7 +406,7 @@ class Validation extends Object {
  * @param integer $check The value the test for decimal
  * @param integer $places if set $check value must have exactly $places after the decimal point
  * @param string $regex If a custom regular expression is used this is the only validation that will occur.
- * @return boolean
+ * @return boolean Success
  * @access public
  */
 	function decimal($check, $places = null, $regex = null) {
@@ -424,12 +427,12 @@ class Validation extends Object {
 		return $this->_check();
 	}
 /**
- * Enter description here...
+ * Validates for an email address.
  *
- * @param string $check
- * @param boolean $deep
- * @param string $regex
- * @return boolean
+ * @param string $check Value to check
+ * @param boolean $deep Perform a deeper validation (if true), by also checking availability of host
+ * @param string $regex Regex to use (if none it will use built in regex)
+ * @return boolean Success
  * @access public
  */
 	function email($check, $deep = false, $regex= null) {
@@ -461,10 +464,25 @@ class Validation extends Object {
 		return false;
 	}
 
+/**
+ * Check that value is exactly $comparedTo.
+ *
+ * @param mixed $check Value to check
+ * @param mixed $comparedTo Value to compare
+ * @access public
+ * @todo Implement
+ */
 	function equalTo($check, $comparedTo) {
 
 	}
 
+/**
+ * Check that value is a file.
+ *
+ * @param mixed $check Value to check
+ * @access public
+ * @todo Implement
+ */
 	function file($check) {
 
 	}
@@ -472,7 +490,7 @@ class Validation extends Object {
  * Validation of an IPv4 address.
  *
  * @param string $check The string to test.
- * @return boolean
+ * @return boolean Success
  * @access public
  */
 	function ip($check) {
@@ -493,8 +511,8 @@ class Validation extends Object {
  *
  * @param string $check The string to test
  * @param int $min The minimal string length
- * @return boolean
-  * @access public
+ * @return boolean Success
+ * @access public
  */
 	function minLength($check, $min) {
 		$length = strlen($check);
@@ -505,7 +523,7 @@ class Validation extends Object {
  *
  * @param string $check The string to test
  * @param int $max The maximal string length
- * @return boolean
+ * @return boolean Success
  * @access public
  */
 	function maxLength($check, $max) {
@@ -513,6 +531,14 @@ class Validation extends Object {
 		return ($length <= $max);
 	}
 
+/**
+ * Checks that a value is a monetary amount.
+ *
+ * @param string $check Value to check
+ * @param string $symbolPosition Where symbol is located (left/right)
+ * @return boolean Success
+ * @access public
+ */
     function money($check, $symbolPosition = 'left') {
     	$this->check = $check;
     	switch ($symbolPosition) {
@@ -526,12 +552,30 @@ class Validation extends Object {
     	return $this->_check();
     }
 
+/**
+ * Validate a multiple select.
+ *
+ * @param mixed $check Value to check
+ * @param mixed $type Type of check
+ * @param string $regex Use custom regular expression
+ * @access public
+ * @todo Implement
+ */
     function multiple($check, $type, $regex= null) {
     	//Validate a select object for a selected index past 0.
     	//Validate a select against a list of restriced indexes.
     	//Validate a multiple-select for the quantity selected.
 	}
 
+/**
+ * Validate that a number is in specified range.
+ *
+ * @param string $check Value to check
+ * @param int $lower Lower limit
+ * @param int $upper Upper limit
+ * @access public
+ * @todo Implement
+ */
 	function number($check, $lower = null, $upper = null ) {
 		if (isset($lower) && isset($upper) && $lower > $upper) {
 			//error
@@ -541,10 +585,26 @@ class Validation extends Object {
 		}
 	}
 
+/**
+ * Checks if a value is numeric.
+ *
+ * @param string $check Value to check
+ * @return boolean Succcess
+ * @access public
+ */
 	function numeric($check) {
 		return is_numeric($check);
 	}
 
+/**
+ * Check that a value is a valid phone number.
+ *
+ * @param mixed $check Value to check (string or array)
+ * @param string $regex Regular expression to use
+ * @param string $country Country code (defaults to 'all')
+ * @return boolean Success
+ * @access public
+ */
 	function phone($check, $regex= null, $country = 'all') {
 		if (is_array($check)) {
 			$this->_extract($check);
@@ -564,6 +624,15 @@ class Validation extends Object {
 		return $this->_check();
 	}
 
+/**
+ * Checks that a given value is a valid postal code.
+ *
+ * @param mixed $check Value to check
+ * @param string $regex Regular expression to use
+ * @param string $country Country to use for formatting
+ * @return boolean Success
+ * @access public
+ */
 	function postal($check, $regex= null, $country = null) {
 		if (is_array($check)) {
 			$this->_extract($check);
@@ -589,6 +658,15 @@ class Validation extends Object {
 		return $this->_check();
 	}
 
+/**
+ * Checks that a value is a valid Social Security Number.
+ *
+ * @param mixed $check Value to check
+ * @param string $regex Regular expression to use
+ * @param string $country Country
+ * @return boolean Success
+ * @access public
+ */
 	function ssn($check, $regex = null, $country = null) {
 		if (is_array($check)) {
 			$this->_extract($check);
@@ -614,16 +692,38 @@ class Validation extends Object {
 		return $this->_check();
 	}
 
+/**
+ * Checks that a value is a valid URL.
+ *
+ * @param string $check Value to check
+ * @return boolean Success
+ * @access public
+ */
 	function url($check) {
 		$this->check = $check;
 		$this->regex = '/\\A(?:(https?|ftps?|file|news|gopher):\\/\\/[\\w\\-_]+(\\.[\\w\\-_]+)+([\\w\\-\\.,\'@?^=%&:;\/~\\+#]*[\\w\\-\\@?^=%&\/~\\+#])?)\\z/i';
 		return $this->_check();
 	}
 
+/**
+ * Runs an user-defined validation.
+ *
+ * @param object $object Object that holds validation method
+ * @param string $method Method name for validation to run
+ * @param array $args Arguments to send to method
+ * @return mixed Whatever method returns
+ * @access public
+ */
 	function userDefined($object, $method, $args) {
 		return call_user_func_array(array(&$object, $method), $args);
 	}
 
+/**
+ * Runs a regular expression match.
+ *
+ * @return boolean Success of match
+ * @access protected
+ */
 	function _check() {
 		if (preg_match($this->regex, $this->check)) {
 			$this->error[] = false;
@@ -634,6 +734,13 @@ class Validation extends Object {
 		}
 	}
 
+/**
+ * Get the values to use when value sent to validation method is
+ * an array.
+ *
+ * @param array $params Parameters sent to validation method
+ * @access protected
+ */
 	function _extract($params) {
 		extract($params, EXTR_OVERWRITE);
 
@@ -657,7 +764,7 @@ class Validation extends Object {
  * Luhn algorithm
  *
  * @see http://en.wikipedia.org/wiki/Luhn_algorithm
- * @return boolean
+ * @return boolean Success
  * @access protected
  */
 	function _luhn() {
@@ -688,6 +795,11 @@ class Validation extends Object {
 		return true;
 	}
 
+/**
+ * Reset internal variables for another validation run.
+ *
+ * @access private
+ */
 	function __reset(){
 		$this->check = null;
 		$this->regex = null;
diff --git a/cake/libs/xml.php b/cake/libs/xml.php
index 64afa1903..1e94eabd9 100644
--- a/cake/libs/xml.php
+++ b/cake/libs/xml.php
@@ -9,10 +9,10 @@
  * PHP versions 4 and 5
  *
  * CakePHP(tm) :  Rapid Development Framework <http://www.cakephp.org/>
- * Copyright 2005-2007, Cake Software Foundation, Inc. 
+ * Copyright 2005-2007, Cake Software Foundation, Inc.
  *                     1785 E. Sahara Avenue, Suite 490-204
  *                     Las Vegas, Nevada 89104
- * 
+ *
  * Licensed under The MIT License
  * Redistributions of files must retain the above copyright notice.
  *
@@ -43,38 +43,44 @@ class XMLNode extends Object {
  * Name of node
  *
  * @var string
+ * @access public
  */
 	var $name = null;
 /**
  * Value of node
  *
  * @var string
+ * @access public
  */
 	var $value;
 /**
  * Attributes on this node
  *
  * @var array
+ * @access public
  */
 	var $attributes = array();
 /**
  * This node's children
  *
  * @var array
+ * @access public
  */
 	var $children = array();
 /**
  * Reference to parent node.
  *
  * @var XMLNode
+ * @access private
  */
 	var $__parent = null;
 /**
  * Constructor.
  *
  * @param string $name Node name
- * @param array  $attributes Node attributes
- * @param mixed  $value Node contents (text)
+ * @param array $attributes Node attributes
+ * @param mixed $value Node contents (text)
+ * @param array $children Node children
  */
 	function __construct($name = null, $attributes = array(), $value = null, $children = array()) {
 		$this->name = $name;
@@ -100,10 +106,11 @@ class XMLNode extends Object {
 		}
 	}
 /**
- * Gets the XML element properties from an object
+ * Gets the XML element properties from an object.
  *
- * @param object $object
- * @return array
+ * @param object $object Object to get properties from
+ * @return array Properties from object
+ * @access private
  */
 	function __objectToNode($object) {
 
@@ -155,9 +162,9 @@ class XMLNode extends Object {
 		return $node;
 	}
 /**
- * Sets the parent node of this XMLNode
+ * Sets the parent node of this XMLNode.
  *
- * @return XMLNode
+ * @access public
  */
 	function setParent(&$parent) {
 		$this->__parent =& $parent;
@@ -165,15 +172,17 @@ class XMLNode extends Object {
 /**
  * Returns a copy of self.
  *
- * @return XMLNode
+ * @return object Cloned instance
+ * @access public
  */
 	function cloneNode() {
-		return $this;
+		return clone($this);
 	}
 /**
  * Append given node as a child.
  *
- * @param XMLNode $child
+ * @param object $child XMLNode with appended child
+ * @access public
  */
 	function &append(&$child) {
 		if (is_object($child)) {
@@ -183,7 +192,7 @@ class XMLNode extends Object {
 			if (func_num_args() >= 2 && is_array(func_get_arg(1))) {
 				$attr = func_get_arg(1);
 			}
-			$tmp = new XMLNode();
+			$tmp =& new XMLNode();
 			$tmp->name = $child;
 			$tmp->attributes = $attr;
 		}
@@ -192,7 +201,8 @@ class XMLNode extends Object {
 /**
  * Returns first child node, or null if empty.
  *
- * @return XMLNode
+ * @return object First XMLNode
+ * @access public
  */
 	function &first() {
 		if(isset($this->children[0])) {
@@ -204,7 +214,8 @@ class XMLNode extends Object {
 /**
  * Returns last child node, or null if empty.
  *
- * @return XMLNode
+ * @return object Last XMLNode
+ * @access public
  */
 	function &last() {
 		if(count($this->children) > 0) {
@@ -216,9 +227,9 @@ class XMLNode extends Object {
 /**
  * Returns child node with given ID.
  *
- * @param string $id Name of childnode
- * @return XMLNode
- *
+ * @param string $id Name of child node
+ * @return object Child XMLNode
+ * @access public
  */
 	function &child($id) {
 		$null = null;
@@ -245,6 +256,7 @@ class XMLNode extends Object {
  *
  * @param string $name Tag name of child nodes
  * @return array An array of XMLNodes with the given tag name
+ * @access public
  */
 	function children($name) {
 		$nodes = array();
@@ -257,9 +269,10 @@ class XMLNode extends Object {
 		return $nodes;
 	}
 /**
- * Gets a reference to the next child node in the list of this node's parent
+ * Gets a reference to the next child node in the list of this node's parent.
  *
- * @return XMLNode A reference to the XMLNode object
+ * @return object A reference to the XMLNode object
+ * @access public
  */
 	function &nextSibling() {
 		$count = count($this->__parent->children);
@@ -273,9 +286,10 @@ class XMLNode extends Object {
 		}
 	}
 /**
- * Gets a reference to the previous child node in the list of this node's parent
+ * Gets a reference to the previous child node in the list of this node's parent.
  *
- * @return XMLNode A reference to the XMLNode object
+ * @return object A reference to the XMLNode object
+ * @access public
  */
 	function &previousSibling() {
 		$count = count($this->__parent->children);
@@ -291,7 +305,8 @@ class XMLNode extends Object {
 /**
  * Returns parent node.
  *
- * @return XMLNode
+ * @return object Parent XMLNode
+ * @access public
  */
 	function &parent() {
 		return $this->__parent;
@@ -300,6 +315,7 @@ class XMLNode extends Object {
  * Returns true if this structure has child nodes.
  *
  * @return boolean
+ * @access public
  */
 	function hasChildren() {
 		if(is_array($this->children) && count($this->children) > 0) {
@@ -311,6 +327,7 @@ class XMLNode extends Object {
  * Returns this XML structure as a string.
  *
  * @return string String representation of the XML structure.
+ * @access public
  */
 	function toString() {
 		$d = '';
@@ -372,6 +389,7 @@ class XMLNode extends Object {
  * Returns data from toString when this object is converted to a string.
  *
  * @return string String representation of this structure.
+ * @access private
  */
 	function __toString() {
 		return $this->toString();
@@ -380,7 +398,8 @@ class XMLNode extends Object {
  * Debug method. Deletes the parent. Also deletes this node's children,
  * if given the $recursive parameter.
  *
- * @param boolean $recursive
+ * @param boolean $recursive Recursively delete elements.
+ * @access private
  */
 	function __killParent($recursive = true) {
 		unset($this->__parent);
@@ -407,18 +426,21 @@ class XML extends XMLNode {
  * Resource handle to XML parser.
  *
  * @var resource
+ * @access private
  */
 	var $__parser;
 /**
  * File handle to XML indata file.
  *
  * @var resource
+ * @access private
  */
 	var $__file;
 /**
  * Raw XML string data (for loading purposes)
  *
  * @var string
+ * @access private
  */
 	var $__rawData = null;
 
@@ -426,6 +448,7 @@ class XML extends XMLNode {
  * XML document header
  *
  * @var string
+ * @access private
  */
 	var $__header = null;
 
@@ -433,6 +456,7 @@ class XML extends XMLNode {
  * XML document version
  *
  * @var string
+ * @access private
  */
 	var $version = '1.0';
 
@@ -440,6 +464,7 @@ class XML extends XMLNode {
  * XML document encoding
  *
  * @var string
+ * @access private
  */
 	var $encoding = 'UTF-8';
 
@@ -447,7 +472,8 @@ class XML extends XMLNode {
  * Constructor.  Sets up the XML parser with options, gives it this object as
  * its XML object, and sets some variables.
  *
- * @param string $input
+ * @param string $input What should be used to set up
+ * @param array $options Options to set up with
  */
 	function __construct($input = null, $options = array()) {
 		parent::__construct('root');
@@ -493,8 +519,9 @@ class XML extends XMLNode {
 /**
  * Initialize XML object from a given XML string. Returns false on error.
  *
- * @param string $in
+ * @param string $in XML string to initialize with
  * @return boolean Success
+ * @access public
  */
 	function load($in) {
 		$this->__rawData = null;
@@ -521,14 +548,15 @@ class XML extends XMLNode {
 			return $this->parse();
 
 		} elseif (is_object($in)) {
-		
+
 		}
 	}
 /**
  * Parses and creates XML nodes from the __rawData property.
  *
+ * @return boolean Success
+ * @access public
  * @see load()
- *
  */
 	function parse() {
 		$this->header = trim(r(a('<'.'?', '?'.'>'), a('', ''), substr(trim($this->__rawData), 0, strpos($this->__rawData, "\n"))));
@@ -592,6 +620,7 @@ class XML extends XMLNode {
  *
  * @param boolean $useHeader Whether to include the XML header with the document (defaults to true)
  * @return string XML data
+ * @access public
  */
 	function compose($useHeader = true) {
 		if (!empty($this->__header)) {
@@ -619,8 +648,9 @@ class XML extends XMLNode {
  * If DEBUG is on, this method echoes an error message.
  *
  * @param string $msg Error message
- * @param integer $code Error code
- * @param integer $line Line in file
+ * @param int $code Error code
+ * @param int $line Line in file
+ * @access public
  */
 	function error($msg, $code = 0, $line = 0) {
 		if(DEBUG) {
@@ -628,10 +658,11 @@ class XML extends XMLNode {
 		}
 	}
 /**
- * Returns a string with a textual description of the error code, or FALSE if no description was found. 
+ * Returns a string with a textual description of the error code, or FALSE if no description was found.
  *
- * @param integer $code
+ * @param int $code Error code
  * @return string Error message
+ * @access public
  */
 	function getError($code) {
 		$r = @xml_error_string($code);
@@ -641,34 +672,48 @@ class XML extends XMLNode {
 // Overridden functions from superclass
 
 /**
- * Enter description here...
+ * Get next element. NOT implemented.
  *
- * @return unknown
+ * @return object
+ * @access public
  */
 	function &next() {
 		return null;
 	}
 /**
- * Enter description here...
+ * Get previous element. NOT implemented.
  *
- * @return null
+ * @return object
+ * @access public
  */
 	function &previous() {
 		return null;
 	}
 /**
- * Enter description here...
+ * Get parent element. NOT implemented.
  *
- * @return null
+ * @return object
+ * @access public
  */
 	function &parent() {
 		return null;
 	}
 
+/**
+ * Return string representation of current object.
+ *
+ * @return string String representation
+ * @access public
+ */
 	function toString() {
 		return $this->compose();
 	}
 
+/**
+ * Destructor, used to free resources.
+ *
+ * @access private
+ */
 	function __destruct() {
 		if (is_resource($this->__parser)) {
 			xml_parser_free($this->__parser);