《PHP_Document_代码注释规范》.pdfVIP

PHP Document 代码注释规范代码注释规范 代码注释规范代码注释规范 PHPDocumentor 是一个用PHP 写的工具，对于有规范注释的php 程序，它能够快速 生成具有相互参照,索引等功能的API 文档。老的版本是 phpdoc 。 1. 什么是phpDocumentor ? PHPDocumentor 是一个用PHP 写的工具，对于有规范注释的php 程序，它能够快速 生成具有相互参照,索引等功能的API 文档。老的版本是 phpdoc，从1.3.0 开始，更名为 phpDocumentor，新的版本加上了对php5 语法的支持，同时，可以通过在客户端浏览器上 操作生成文档，文档可以转换为PDF,HTML,CHM 几种形式，非常的方便。 PHPDocumentor 工作时，会扫描指定目录下面的php 源代码，扫描其中的关键字，截 取需要分析的注释，然后分析注释中的专用的tag，生成 xml 文件，接着根据已经分析完的 类和模块的信息，建立相应的索引，生成xml 文件，对于生成的xml 文件，使用定制的模 板输出为指定格式的文件。 2. 安装phpDocumentor 和其他pear 下的模块一样，phpDocumentor 的安装也分为自动安装和手动安装两种 方式，两种方式都非常方便： a． 通过pear 自动安装 在命令行下输入 pear install PhpDocumentor b． 手动安装 在/下载必威体育精装版版本的PhpDocumentor （现在是1.4.0），把 内容解压即可。 3．怎样使用PhpDocumentor 生成文档 命令行方式： 在phpDocumentor 所在目录下，输入 Php –h 会得到一个详细的参数表，其中几个重要的参数如下： -f 要进行分析的文件名，多个文件用逗号隔开 -d 要分析的目录，多个目录用逗号分割 -t 生成的文档的存放路径 -o 输出的文档格式，结构为输出格式：转换器名：模板目录。 例如：phpdoc -o HTML:frames:earthli -f test.php -t docs Web 界面生成 在新的phpdoc 中，除了在命令行下生成文档外，还可以在客户端浏览器上操作生成文 档，具体方法是先把PhpDocumentor 的内容放在apache 目录下使得通过浏览器可以访问 到，访问后显示如下的界面： 点击files 按钮，选择要处理的php 文件或文件夹，还可以通过该指定该界面下的Files to ignore 来忽略对某些文件的处理。 然后点击output 按钮来选择生成文档的存放路径和格式. 最后点击create，phpdocumentor 就会自动开始生成文档了，最下方会显示生成的进 度及状态，如果成功，会显示 Total Documentation Time: 1 seconds done Operation Completed!! 然后，我们就可以通过查看生成的文档了，如果是pdf 格式的，名字默认为 documentation.pdf 。 4 ．给php 代码添加规范的注释 PHPDocument 是从你的源代码的注释中生成文档，因此在给你的程序做注释的过程， 也就是你编制文档的过程。 从这一点上讲，PHPdoc 促使你要养成良好的编程习惯，尽量使用规范，清晰文字为你 的程序做注释，同时多多少少也避免了事后编制文档和文档的更新不同步的一些问题。 在phpdocumentor 中，注释分为文档性注释和非文档性注释。 所谓文档性注释，是那些放在特定关键字前面的多行注释，特定关键字是指能够被 phpdoc 分析的关键字，例如class，var 等，具体的可参加附录1. 那些没有在关键字前面或者不规范的注释就称作非文档性注释，这些注释将不会被 phpdoc 所分析，也不会出现在你产生的api 文当中。 3.2 如何书写文档性注释: 所有的文档性注释都