这些PHPDOC属性的目的是什么?

时间:2009-11-21 13:20:23

标签: php syntax properties phpdoc

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

@category - 究竟是什么?

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

2 个答案:

答案 0 :(得分:10)

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

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

要记住关于@package的关键是,它是组织文档的途径 ...它与代码的执行方式无关。现在,显然你更有可能想要根据你在概念上如何组织你的应用程序的各个部分来组织文档,所以在这个意义上,“包”感觉它是< em>组织代码 ... 但最后,package标签是关于你希望phpDocumentor如何组织文档的。

至于类别标签,我不相信任何输出转换器使用除了PEAR项目之外的任何输出转换器。类别用于将一组包收集到一个大包中。但同样,这只与PEAR有关,只要已经将哪些功能融入输出转换器。 可以忽略此标记,如果您要... 不能忽略包标记,因为它是phpDocumentor如何组织文档的核心。

现在,关于使用@package的例子,手册中有一些,如上所述。简而言之,您需要在每个文件的文件级docblock中使用包标签(这是全局范围的函数和常量将从其中获取“包”),以及每个类的docblock中。如果您没有为这些代码元素提供包值,则phpDocumentor必须将它们全部转储到“默认”包中。

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

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

(我包含了更多网址,但stackoverflow不允许我发布多个网页...)

答案 1 :(得分:4)

@Category

  

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

     

这是   直接适用于   XML:DocBook / peardoc2转换器,和   可以被其他转换器使用。其他   转换器与phpDocumentor打包在一起   忽略该类别,但这可能   未来版本的变化。也是   可以动态指定   使用-dc的类别,   --defaultcategoryname命令行开关

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

@package

  

@package只能用于文档   程序性页面或类。

     

包用于帮助您   逻辑上分组相关元素。您   写类到相关的组   功能和数据在一起,和   phpDocumentor代表内容   文件(函数,定义和   包括)作为“程序页面”。一个   package用于对类进行分组   程序页面在一起   目录组相关的方式   文件在一起。

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