Как использовать @package & @subpackage в phpdoc?

Question

Мне интересно, как мне использовать @package & @subpackage для класса документа.

Допустим, у меня есть следующий класс

class My_Controller_Action_Helper_MyHelperAction extends Foo_Bar {}

Должно ли это быть:

@category    My
@package     Controller
@subpackage  Action_Helper

или

@category    My
@package     Controller
@subpackage  Action_Helper_MyHelperAction

или

@category    My
@package     Controller_Action
@subpackage  MyHelperAction

или

@category   My
@package    My_Controller_Action
@subpackage MyHelperAction

Что если использовать пространство имен вместо '_'?

Answer 1

Во-первых: если вы используете «_» или «\» (разделитель пространства имен), это не должно влиять на ваше решение, как вы будете комментировать свои классы. Подчеркивание «_» происходит от возраста, предшествующего пространству имен, и «действует как» разделитель пространства имен, за исключением того, что он не создает никаких пространств имен. Поэтому «My_Controller_Action» следует рассматривать как «Action» в «My_Controller».

Однако то, как вы используете @package и / или @subpackage, действительно является вашим решением. Например, я вообще не использую @category, а @subpackage - это все, что находится после "второго" пространства имен. Позвольте мне объяснить: я следую стандарту PSR-0, где пакет структурирован в \<Vendorname>\<packagename>\<subpackage>\... (или «_» вместо «\», в зависимости от версии). Тогда @package <vendorname>.<package> и @subpackage <subpackage>.

Вывод: решать только вам :) Документатор может распределять различные структуры вашего кода в зависимости от используемых вами тегов и способа их использования. Просто попробуйте.

Answer 2

Я использую @package для имени пакета, к которому этот файл относится ... удивительно :) Например, если это плагин xyz, @package для всех файлов, которые принадлежат этому пакету.

для doxygen (который я использую) нет такой вещи, как @subpackage, хотя вы можете сделать свой собственный.Например: http://www.doxygen.nl/manual/commands.html

Для doxygen вы можете использовать что-то вроде @package my.awesome.package, которое разбивает его на «подпакеты»

Вы действительно можете использовать его для чего угоднокак это имеет смысл и является последовательным.сначала решите, что вы хотите использовать, а затем посмотрите рекомендации / документы для этого приложения, поскольку они все разные