How to use @package & @subpackage in phpdoc?

Question

I am wondering how should I use @package and @subpackage for the doc class.

let's say i have the following class

class My_Controller_Action_Helper_MyHelperAction extends Foo_Bar {} 

Should it be:

 @category My @package Controller @subpackage Action_Helper 

or

 @category My @package Controller @subpackage Action_Helper_MyHelperAction 

or

 @category My @package Controller_Action @subpackage MyHelperAction 

or

 @category My @package My_Controller_Action @subpackage MyHelperAction 

What if I use a namespace instead of '_'?

Answer 1

First: If you use "_" or "\" (a namespace delimiter), this should not affect your decision about how you comment on your classes. The underscore "_" occurs from age to the namespace and acts as a namespace delimiter, except that it does not create a namespace. Therefore, "My_Controller_Action" should be considered as "Action" in "My_Controller".

However, how you use @package and / or @subpackage is really your solution. For example, I don’t use @category at all, and @subpackage is all after the “second” namespace. Let me explain: I follow the PSR-0 standard, where the package is structured in \<Vendorname>\<packagename>\<subpackage>\... (or "_" instead of "\", depending on version). Then @package <vendorname>.<package> and @subpackage <subpackage> .

Conclusion: it is up to you :). A document can carry various structures of your code, depending on the tags you use and how you use them. Just try it.

Answer 2

I use @package to name the package to which this file belongs ... surprise :) for example, if its plugin is called xyz @package for all files belonging to this package.

there is no such thing as @subpackage for doxygen (which I use), although you can make your own. for example: http://www.stack.nl/~dimitri/doxygen/commands.html

For doxygen, you can use something like @package my.awesome.package, which breaks it down into "subpackages"

You can really use it for anything if it makes sense and is consistent. first decide what you want to use, and then see the recommendations / documents for this application, as they are all different