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

• A file header (general description) is required. It must start with /** and end with */ and have a * beginning each line in between.
  
  
• A descriptive comment must be given
  
  
• At least one author tag (@author) is required (ideally, at least two authors will have knowledge of a file)
  
  
• Each author tag must have an email address in <>'s
  
  
• A developer need not have typed a file him/herself to count as an author - participation in design/planning counts as well
  
  
• A see tag (@see) may be added to reference other URLs
  
  

Constants

• All defined constants must be documented with an @const tag, a valid type, and a description.
• Constants must be all uppercase

Class member variables/attributes

• All declared variables must be documented with a @field tag
  
  
• @field tags must have a valid type, valid access level, and a description
  
  

Functions/methods

• All functions must have a header. It must start with /** and end with */ and have a * beginning each line in between.
  
  
• A descriptive comment must be given
  
  
• A @param tag must be given for each of the function's parameters
  
  
• @param tags must have a valid type and a description
  
  
• If a parameter is optional, put [optional] after the type.
  
  
• If a parameter is optional, remember to describe the default value.
  
  
• All functions must have a @return tag, even if it's just @return void
  
  
• @return tags must have a valid type
  
  
• All functions must have an @access tag with a valid access level
  
  
• If a function can produce any error objects, the types of those objects must be listed with @throws tags
  
  
• If a function may be called with different combinations of parameters, use @funcsig to describe each one
  
  
• If using @funcsig you must include the name of your parameters after your @param tags (@param [type] name description)
  
  
• If a function is static, indicate that with @static
  
  

Valid Tags

• author Who wrote or contributed to the file.
  
  
• const Type and description of constant.
  
  
• field Access, type, and description of field.
  
  
• param Type and description of parameter.
  
  
• return Type of returned value.
  
  
• access Access level of field or function (public, protected, private).
  
  
• throws Type of error function throws.
  
  
• see Other URL to reference.
  
  
• funcsig Alternate function signature.
  
  
• static Function is meant to be called statically.
  
  

Valid Types

• [class name] The name of any class in Knickers or your app.
  
  
• boolean
  
  
• int
  
  
• float
  
  
• string
  
  
• array
  
  
• object
  
  
• constant
  
  
• resource
  
  
• NULL
  
  
• mixed
  
  
• void
  
  

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;
	}
	
}

email

password