CODEWITHSUNDEEP
phpcodeigniterdocumentationphpdoc
Adamantus
Adamantus

Reputation: 821

How to use phpDocumentor for CodeIgniter

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,

Upvotes: 2

Views: 4220

Answers (2)

raidenace
raidenace

Reputation: 12826

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

Upvotes: 3

Jamshid Hashimi
Jamshid Hashimi

Reputation: 7825

@package can only be used to document procedural pages or classes.

Packages are used to help you logically group related elements. You write classes to group related functions and data together, and phpDocumentor represents the contents of files (functions, defines, and includes) as "Procedural Pages." A package is used to group classes and procedural pages together in the same manner that a directory groups related files together.

You can find answers to your questions and more in phpDocumentor guide here

Upvotes: 0

Related Questions