Databug

Friday, May 19, 2006

phpDocumentor Commenting Style

I'm a vigil (somewhat anal) commentor. A good part of the art in coding for me rests with neat, well formatted, and consistent comments. Over the last couple years I've developed my own style, idiosyncratic perhaps, but neatly formatted and easy to pick up at a glance. (You can see examples of it on my design blog.)

For the sake of this project, however, I am making a concerted effort to use the phpDocumentor style. I'm slowly getting the hang of it. There is extensive online documentation, but I'd trade it all for one complete demo file. (I must have someone on my drive somewhere.)

phpDocumentor organizes comments around DocBlocks. For a class, I count four key DocBlocks.

1. The Page Block
/**
* Package PackageName
* desciption of package here --
*
* @package PackageName
* @author Name
*/


2. The Class Block
/**
* Class ClassName
*
* NOTES
* notes here
*
* @package PackageName
* @author Name
* @version
*/


3. The Variable Block
/**
* @access public
* @var string
*/


4. The Method Block
/**
* Short description of method
* Usage: $result = $_O['data_obj']->Method($string, $integer, $float, $ARRAY);
*
* @access public/private
* @param string $string
* @param integer $integer
* @param float $float
* @param array $ARRAY
* @return string $return
*/

 

0 Comments:

Post a Comment

<< Home