How to use @package & @subpackage in phpdoc?

I'm wondering how I should use @package & @subpackage for class doc.

let say I've 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_My开发者_如何学PythonHelperAction

or

@category    My
@package     Controller_Action
@subpackage  MyHelperAction

or

@category   My
@package    My_Controller_Action
@subpackage MyHelperAction

What if use namespace instead of '_'?

First: If you use "_" or "\" (the namespace separator) should not influence your decision, how you annotate your classes. The underscore "_" comes from a pre-namespace age and "acts like" the namespace separator, except that it not create any namespaces. So "My_Controller_Action" should be treated as "Action" in "My_Controller".

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

Conclusion: Its up to you :) A documentor may gerenate different structures of your code, depending on the tags you use and how you use them. Just try it out.

If you've came across this answer in 2020, both @category and @subpackage tags are considered deprecated, so please don't use them anymore.

Instead of that, you should use @package to provide the required logical sub-division.

According to https://docs.phpdoc.org/latest/guide/references/phpdoc/tags/category.html and https://docs.phpdoc.org/latest/guide/references/phpdoc/tags/subpackage.html :

Important This tag is considered deprecated and may be removed in a future version of phpDocumentor. It is recommended to use the @package tag’s ability to provide multiple levels.

Important This tag is considered deprecated and may be removed in a future version of phpDocumentor. It is recommended to use the @package tag’s ability to provide multiple levels.

i use @package for the name of the package this file belongs to... surprise :) eg if its a plugin called xyz the @package for all files that belong in that package.

for doxygen (which i use) there is no such thing as a @subpackage although you can make your own. eg: http://www.doxygen.nl/manual/commands.html

For doxygen you can use something like @package my.awesome.package which breaks it down in to 'sub packages'

You can really use it for anything as long as it makes sense and is consistent. first decide what you want to use and then look at the recommendations / docs for that application as they are all different