如何在 phpdoc 中使用 @package 和 @subpackage？答案

【问题标题】：How to use @package & @subpackage in phpdoc?如何在 phpdoc 中使用 @package 和 @subpackage？
【发布时间】：2011-07-30 18:48:06
【问题描述】：

我想知道如何将@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

如果使用命名空间而不是'_'会怎样？

【问题讨论】：

根据网站phpdoc.org，关于类别和子包：“这个标签被认为是不推荐的，可能会在未来的phpDocumentor版本中被删除。建议使用@package标签提供的能力多个级别。”

标签： php phpdoc

【解决方案1】：

如果您在 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 标签提供多层次的能力。

【讨论】：

【解决方案2】：

我使用@package 作为这个文件所属的包的名称......惊喜:) 例如，如果它是一个名为 xyz 的插件，那么属于该包的所有文件的@package。

对于 doxygen（我使用），没有 @subpackage 这样的东西，尽管您可以自己制作。例如：http://www.doxygen.nl/manual/commands.html

对于 doxygen，您可以使用 @package my.awesome.package 之类的东西，将其分解为“子包”

只要有意义且始终如一，您就可以真正将其用于任何事情。首先决定您要使用什么，然后查看该应用程序的建议/文档，因为它们都是不同的

【讨论】：

【解决方案3】：

首先：如果你使用“_”或“\”（命名空间分隔符）不应该影响你的决定，你如何注释你的类。下划线“_”来自一个前命名空间时代，“行为类似于”命名空间分隔符，只是它不创建任何命名空间。所以“My_Controller_Action”应该被视为“My_Controller”中的“Action”。

但是，您如何使用@package 和/或@subpackage 确实是您的决定。例如，我根本不使用@category，@subpackage 是“第二个”命名空间之后的所有内容。让我解释一下：我遵循 PSR-0 标准，其中包的结构为\<Vendorname>\<packagename>\<subpackage>\...（或“_”而不是“\”，具体取决于版本）。然后@package <vendorname>.<package> 和@subpackage <subpackage>。

结论：由您决定 :) 根据您使用的标签和使用方式，文档生成器可能会生成不同的代码结构。试试看吧。

【讨论】：