的标识符是预定义的,它们形成了文档解析器如何解释注释的规则。 /** 这里是 PHPDoc 注释。 @param bool $foo Foo 给函数传递了一些信息 */ function bar($foo) {} 值得注意的是,@param 标签描述了函数的 $foo 参数。这是元
数据,可以稍后被解析 器阅读,从而数据关于 $foo 的文档。标签的格式允许添加一些附加的元数据,例如变量的 类型、变量的名称以及对操作的描述。所有的 PHPDoc 标签都遵循这一基本格式。 @param 标签只是大量标签中的一个。 下面列出了应用于 PHP5 以及之后版本的最常用 的一些 PHPDoc 标签。要查看完整的标签
列表,可参见 manual.phpdoc.org/ 。 标签 @access public|private|protected 说明 描述了访问级别。当使用反射技术时,这个 标签不是很有用,这是因为 API 能够自动获 取这一特性。在 PHPDoc 中,用它可略去私 有成员的文档生成 帮助获得负责某个特定元素的人的信息(强 烈推荐使用这一标签)
@author Author Name [
]
@copyright Copyright Information @deprecated [version information] @exmple [path|url] description
可指定代码的版权所有者 可通知代码的使用者这个元素不再被使用并 且已经被替换 可引用一个例子,阐释如何使用这个元素。 第二个参数可以是一个路径也可以是一个完 整的 URL 可用来表示希望让文件源出现在文档中。这 一标签只能出现在页面级别的块中,在其他 地方出现将会被忽略 说明了全局变量的数据类型。这一标签必须 紧贴在全局变量的前面,并且只对 phpDocumentor 解析器起作用。 对于基于反射 技术的解析器用处不大 通知解析器忽略这个元素,并且不将它包含 在文档中 可以隐藏特定的信息,使之不出现在公开文 档中。可以用在内嵌的注释内容中或者新行 注释中 url 指定此软件授权信息的 URL,还可以说 明授权者的 url 在文档中包含一个连接。 这个标签可以用 在内嵌的内容中 说明函数和方法关联的参数。这可能是最重 要的标签。变量名称参数可以包括,…符号 以表示函数可以传入不定量的其他参数 说明了函数或方法返回的数据类型。这可能 是第二个重要的标签,并且它是在 PHP 中包 含关于返回数据的元数据的唯一方法。推荐 所有具有返回值的函数使用这一标签 引用另外一个元素的文档。在这里可以使用 不同类型的指针,包括文件、函数名称、类 方法以及其他许多类型的指针。多个指针值 可以用逗号隔开。这个标签也可以用在内嵌 的内容中 用于说明这个元素第一次出现的版本信息 用于包括内嵌于文档中的相关联元素的部分 源代码内容。 包含了待完成工作的信息,或者待解决问题 的信息。 说明了类变量的类型,类变量也被看作是属 性 指定了元素的当前版本号
@filessource
@globale datatype description
@ignore @internal
@lincense url [lincense] @link url [description] @param datatype $variablename[, …] description @return datatype description
@see reference
@since version [information] @source startoffset [endoffset] @todo description @var datatype @version
下面的代码演示了一个函数上的一些典型的 PHPDoc 注释。
/** * 这个函数连接了两个字符串 * * 通过获得第一个字符串,并将它添加到第二个字符串上,最后返回结果, * 它完成了这一功能 * @param string $string1 左边的字符串 * @param string $string2 右边的字符串 * @return string A 包含了合并后内容的字符串 * @todo 添加一个连接字符参数 */ Function concatTwoStrings($string1, $string2) { return $string1 . $string2; } 现在已经编写了所有的文档块和标签, 那么如果使用它们来创建手册呢?其中一方法是 使用 phpDocumentor 解析器,也可以使用反射技术来解析这些信息。现在将介绍如何使用 phpDocumentor。获得 phpDocumentro 解析器工具最简单的方法是从 PEAR 包中安装它。 pear install PhpDocumentor 这样就可以使用 phpdoc 命令了。首先可以尝试一下以下命令。 phpdoc –f somefile.php –t /path/to/output/directory 建议将输出路径指定为 Web 根目录,这样就可以从 Web 浏览器中查看输出结果了。Phpdoc 命令提供了大量的输出选项,以下为其中部分选项: HTML:frames:default, 输出为 HTML 桢格式; HTML:Smarty:default, 输出为 Smarty 模板格式; CHM:default:default, 输出为 Windows 帮助文件格式; PDF:default:default, 输出为 PDF 格式。 使用以下命令格式添加 –o 选项就可以指定这些输出选项了。 output:converter:templatedir 使用 –h 选项可以显示所有的选项和参数。 在 phpdoc 命令运行后,将会在输出目录中出现一个 HTML 文件。可以使用 Web 浏览 器查看这个文件,其中包含了 PHP 文件中的代码信息。