Knickers: Change your underwear!
Code Documentation Standards

The following applies to php files, and php classes where appropriate. Following this standard will make your code compliant with the Knickers API

File headers

Constants

Class member variables/attributes

Functions/methods

Valid Tags

Valid Types

Example

/**
* Top comment
*
*@author [name] []
*@author Fred Smith <fred@smith.com>
*@author Joe Jones <joe@jones.com>
*/

require_once KNICKERS_ROOT.'/common/cls/Object.class.php';

define('[const]', [val]); //@const [type] [description]
define('MY_CONSTANT', 1); //@const int My constant

class Whatever extends Object
{
	var [somevar]; //@field [type] [access] [description]
	var $somePrivateVar; //@field int private some secret variable
	
	/**
	* [function information..]
	*
	*@param [type] [description]
	*@return [type]
	*@access [access]
	*@throws [Error object]
	*/
	function myFunction($param)
	{
		
	}
	
	/**
	* Looks up a user based on first and last name, a user object, or email address
	*
	*@param string $firstName user's first name
	*@param string $lastName user's last name
	*@param object $user User
	*@param string $emailAddress user's email address...	
	*@funcsig function lookupUser($firstName, $lastName);	
	*@funcsig function lookupUser($user);	
	*@funcsig function lookupUser($emailAddress);		
	*@return User
	*@access public
	*@throws Error_DBA
	*/
	function lookupUser($param1, $param2 = NULL)
	{
		
	}	
	
	/**
	* Validates some passed data
	*
	*@param array data to validate
	*@return boolean
	*@access public
	*@throws Error_DBA
	*@throws Error_CDMJ
	*/
	function validate($data)
	{
		if($db->doSomething() === CDMJ_ERROR)
		{
			// this doesn't do much - it's just an example of different errors
			$err = $db->getError();
			if(is_a($err, 'Error_DBA'))
				return $this->setCDMJError(new Error_DBA($err));
			else
				return $this->setCDMJError(new Error_CDMJ($err));
		}
		
		if($data == $somethingBad)
		{
			$this->addInvalidDataError(new Error_InvalidData());
			return FALSE;
		}
		
		return TRUE;
	}
	
}