3

一般来说,PHPDOC 属性是不言自明的,但我很难理解这些:

@category- 这到底是什么?

@package- 有人可以提供有关此属性使用的示例吗?

4

2 回答 2

10

包标签是您在代码中使用的关键组织标签。当 phpDocumentor 生成文档时,它会将元素收集到您设置的包中。在某些情况下,您可能会选择为整个代码库仅使用一个包名称(@package MyPackage),这样所有文件、类等都将出现在该包的文档中。

但是,如果您选择以更模块化的方式组织事物,则可以将所有面向 Web 的过程文件放在一个包中(@package Webpages),将所有面向数据库的类放在一个包中(@package DatabaseHandlers),将所有实用程序类放在一个包中( @package Utilites),等等。

关于@package,要记住的关键是它是组织文档的途径……它与代码的执行方式无关。现在,显然您更可能希望根据您在脑海中概念性地组织应用程序的各个部分来组织文档,因此从这个意义上说,“包”感觉就像是在组织代码...... 在最后,包标签是关于你希望 phpDocumentor 如何组织文档的。

至于类别标签,我不相信任何输出转换器都使用它,除了对 PEAR 项目重要的那些。类别用于将一组包收集到一个大包中。但同样,这仅与 PEAR 相关,就输出转换器中已经包含哪些功能而言。如果你愿意,你可以忽略这个标签……你不能忽略 package 标签,因为它是 phpDocumentor 如何组织文档的核心。

现在,关于使用@package 的示例,手册中有一些,正如seegee 已经提到的。长话短说,您需要在每个文件的文件级文档块(这是全局范围的函数和常量从中获取“包”的地方)和每个类的文档块中都有一个包标签。如果您不为这些代码元素提供包值,phpDocumentor 将被迫将它们全部转储到“默认”包中。

最后一点...如果您不关心将代码组织到各种包中,并且不想编辑所有文件以添加 @package 标签,则可以改用 -dn 运行时参数来设置默认包名称 [1]。这告诉 phpDocumentor 将您在该参数中提供的包名称用于它想要包名称的所有“未打包”代码元素。还有一个 -dc 参数来设置默认的类别名称,但就 phpDocumentor 而言,这并不重要。

[1] -- http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#using.command-line.defaultpackagename

(我包含了更多的 URL,但 stackoverflow 不会让我发布多个……)

于 2009-11-21T14:18:01.727 回答
4

@类别

@category 标签用于将包组组织在一起。

这直接适用于 XML:DocBook/peardoc2 转换器,并且可以被其他转换器使用。与 phpDocumentor 打包的其他转换器会忽略该类别,但这可能会在将来的版本中更改。也可以使用 -dc, --defaultcategoryname 命令行开关动态指定类别

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.category.pkg.html

@包裹

@package 只能用于记录过程页面或类。

包用于帮助您对相关元素进行逻辑分组。您编写类来将相关的函数和数据组合在一起,而 phpDocumentor 将文件的内容(函数、定义和包含)表示为“过程页面”。包用于将类和过程页面组合在一起,其方式与目录将相关文件组合在一起的方式相同。

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.package.pkg.html

于 2009-11-21T13:22:49.573 回答