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

Question

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

@category - 这究竟是什么？

@package - 有人可以提供一些关于这个属性用法的例子吗？

Answer 1

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

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

要记住关于@package的关键是它是组织文档的途径......它与代码的执行方式无关.现在,显然你更有可能想要根据你在脑中概念性地组织应用程序的方式来组织文档,这样在这个意义上,"包" 会觉得它正在组织代码 ...... 但是最后,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

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