Question

I’ve built quite an extensive web application and I was looking through the style guide for CodeIgniter (CI) to see how to do comments. It has things like this for classes and methods:

/** 
* Super Class 
* 
* @package Package Name 
* @subpackage Subpackage 
* @category Category 
* @author Author Name 
* @link http://example.com 
*/ 

class Super_class {}

/** 
* Encodes string for use in XML 
* 
* @access public 
* @param string 
* @return string 
*/ 

function xml_encode($str){}

This is fine but then I don’t know what to fill out for these options. I don’t really have @package, I just have some models and controllers. In Java I might use packages for security but not in CI, it’s just the MVC. I always have things like, project_mode, projects (controller) and add_project_view.php for example.

Also what is the format for @category? The phpDocumentor docs say, “The @category tag is used to organize groups of packages together”. Again, no packages!

Secondly, what about parameters in methods? Sometimes I have two strings and an array or an integer and an array, what is the format for @param?

Thanks,

Answer 1

Package, subpackage and category are for better structuring your code logically. It doesn’t need to be there for every project/code file you have.

Params in methods on the other hand are very useful to be defined, because we need to know what they are when reading the documentation because we need to pass them while calling those methods in our code.

A sample would be like so:

/**
 * Sample function
 * @param string $param1 name of person
 * @param integer $param2 age of person 
 * @return string 
 */
function person($name, $age)
{
    return "$name is $age years old";
}