PHP编程

phpDocumentor

phpDocumentor 是一款用于通过内联注释自动生成易于阅读的文档的工具。

为什么使用 phpDocumentor?

理想的文档应该具备两个特性。首先，它应该容易维护并保持更新。其次，它应该便于读者阅读和浏览。通常这两个目标是相互矛盾的。通过使用类似 javadoc 和 phpDocumentor 这样的工具，您可以同时实现这两个目标。在编写文档时，您只需在代码中插入特殊注释。然后，phpDocumentor 会解析您的代码，并生成易于使用的文档，格式可以是 HTML、DocBook 或 PDF。

基本用法

phpDocumentor 会识别 C 风格的注释，这些注释的开头会有两个星号。

/**
 *
 */

这些注释被称为 DocBlock 注释。通过将这些注释放在代码元素之前，phpDocumentor 会为该元素生成文档。例如，如果我想要为 “RhesusMacaque” 类生成文档，我会在它之前放置一个 DocBlock 注释。

/**
 * 这是 Rhesus Macaque 的文档
 */
class RhesusMacaque
{
  ...
}

phpDocumentor 注释的格式

phpDocumentor 的 DocBlock 注释有三个部分。第一部分是对代码元素的简短总结，最好不要超过一句话。接下来是描述元素的几句话（可选）。最后是标签的序列。

/**
 * Rhesus Macaques 通过一个秘密的阴谋统治世界
 *
 * Rhesus Macaques 已经悄悄地观察人类文明
 * 数百年。他们通过各种机制悄悄地影响了历史事件。
 * 查看类成员以了解更多详情。
 *
 */
class RhesusMacaque
{
  ...
}

标签

标签可以插入到 DocBlock 中，以便更详细地描述代码元素的某些部分。它们提供了如函数的返回类型或代码作者等数据。标签以 “@” 符号开头，并采用以下格式：

* @tagname properties

每种元素类型都有不同的标签集合来描述它。可以查看 phpDocumentor 文档中记录的元素。

内联标签

phpDocumentor 记录的元素。

生成文档

以下命令：

phpdoc --target /var/www/phpdoc --output "HTML:Smarty:php" --directory /var/www/app --filename **/*.php

将会从位于 /var/www/app 目录下的 PHP 文件中生成文档。

有关完整的输出格式列表，请参见 phpDocumentor 网站。

注意：output 参数的值是区分大小写的。

错误

1. 错误提示：Converter HTMLsmartyConverter specified by --output command-line option is not a class
   • smarty 中的 s 应该大写。
2. 错误提示：template directory "/var/www/pear/PhpDocumentor/phpDocumentor/Converters/HTML/Smarty/templates/php/" does not exist
   • php 应该大写。

外部链接

• phpDocumentor 官网
• phpDOC 官网