How to use phpDocumentor for CodeIgniter

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,

raidenace · Accepted Answer · 2012-09-26 19:35:56Z

3

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

edited Sep 26, 2012 at 19:35

answered Sep 26, 2012 at 17:11

raidenace

12.8k1 gold badge34 silver badges35 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

Adamantus Over a year ago

Thanks for the help on the params.

Jamshid Hashimi · Accepted Answer · 2012-09-26 18:01:57Z

0

@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

answered Sep 26, 2012 at 18:01

Jamshid Hashimi

7,8512 gold badges31 silver badges28 bronze badges

2 Comments

Adamantus Over a year ago

(I did reference the guide in my original post.) By the explanation here I would say that an example package would be models or controllers?

ashnazg Over a year ago

Yes, a good basic "package" structure for an MVC app would be models, controllers, and views. The "package" grouping tag is only for a logical grouping of things, based on how you want them presented in your docs. They have no bearing on code execution, unless you choose to align package members based on that. This tag predates namespacing, which was added in PHP 5.3, so it was the only means of "organizing" your docs in any manner.

Collectives™ on Stack Overflow

How to use phpDocumentor for CodeIgniter

2 Answers 2

1 Comment

2 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

1 Comment

2 Comments

Your Answer

Sign up or log in

Post as a guest

Related