Writing Documentation

All code to be formally released must be accompanied with complete API documentation, the format of which follows PHPDocumentor.

As an example, we explain how to write documentation for the TControl class, which is located in the file TControl.php. As we see in the following, the documentation mainly includes:

• a doc block for the code file,
• a doc block for each class,
• and a doc block for each class method.

Each doc block may start with one line of brief explanation of the documenting target (file, class or method), followed by a detailed explanation in one or several paragraphs.

Doc blocks for class methods also contain information about parameters, return values and possible exceptions.

 
<?php
/**
 * ...brief explanation of this file in one line (required).
 *
 * ...detailed explanation of the file (optional).
 *
 * @author Qiang Xue <qiang.xue@gmail.com>     (author information)
 * @link http://www.pradosoft.com/             (link to pradosoft.com)
 * @copyright Copyright &copy; 2005 PradoSoft  (copyright info)
 * @license http://www.pradosoft.com/license/  (license info)
 * @version $Revision: $  $Date: $             (version info)
 * @package System.Web.UI                      (package info)
 */
 
/**
 * ...brief explanation of the class in one line(required).
 *
 * ...detailed explanation of the class (required).
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @version $Revision: $  $Date: $
 * @package System.Web.UI
 * @since 3.0
 */
class TControl extends TApplicationComponent implements IRenderable, IBindable
{
	......
 
	/**
	 * ...brief explanation of the method in one line (optional).
	 * ...detailed explanation of the method (optional).
	 * @param string ID of the control to be looked up
	 * @return TControl|null the control found, null if not found
	 * @throws TInvalidDataValueException ...
	 */
	public function findControl($id)
	{
		......
	}
 
	......      
}
?>