How to use @package & @subpackage in phpdoc?

Question

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_MyHelperAction

or

@category    My
@package     Controller_Action
@subpackage  MyHelperAction

or

@category   My
@package    My_Controller_Action
@subpackage MyHelperAction

What if use namespace instead of '_'?

Answer 1

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.