Блог

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

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

 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
  

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

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

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

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

Если вы сталкивались с этим ответом в 2020 году, оба тега @category и @subpackage считаются устаревшими, поэтому, пожалуйста, не используйте их больше.

Вместо этого вам следует использовать @package для предоставления требуемого логического подразделения.

Согласно https://docs.phpdoc.org/latest/guide/references/phpdoc/tags/category.html и https://docs.phpdoc.org/latest/guide/references/phpdoc/tags/subpackage.html :

Важно, что этот тег считается устаревшим и может быть удален в будущей версии phpDocumentor. Рекомендуется использовать возможность тега @package предоставлять несколько уровней.

Важно, что этот тег считается устаревшим и может быть удален в будущей версии phpDocumentor. Рекомендуется использовать возможность тега @package предоставлять несколько уровней.

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

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

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

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