I'm working on a standard way to comment each class. This will be helpful for two reasons...
1) It improves the generated API displaying comments in a more structure way.
2) The class file itself will have more/better information for developers thus making it easier for new comers to comprehend and contribute to the code base.
Here is a sample class.php file with important elements commented. Do you have any suggestions?
This appears at the front of every file...
<?PHP
/**
* PHP OpenBiz
*
* LICENSE
*
* This source file is subject to the GPL license that is bundled
* with this package in the file LICENSE.txt.
*
* @package BizSystem
* @copyright Copyright (c) 2005 through 2009, Rocky Swen
* @license http://www.gnu.org/licenses/gpl.txt GPL
*/
This appears at the beginning of every class...
/**
* A class that is treated as the bi-direction proxy of client. Through this class,
* others can get client form inputs, redraw client form or call client javascript functions.
*
* @author Rocky Swen <rocky@phpopenbiz.org>
* @version 1.2 2008-04-01
*/
This is for class variables...
/**
* why do i exist?
* @var array
*/
protected $m_RequestArgs;
This appears at the beginning of every method
/**
* get the client form data passed by GET or POST
*
* @param string $name - Comments
* @return string $val - Comments
*/
public function GetRequestParam ($name)
{
$val = (isset($_REQUEST[$name]) ? $_REQUEST[$name] : "");
return $val;
}
