快速业务通道

PHP Document 代码注释规范

作者 佚名技术 来源 NET编程 浏览 发布时间 2012-05-25

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. 手动安装
在http://manual.phpdoc.org/下载最新版本的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如何书写文档性注释:
所有的文档性注释都是由/**开始的一个多行注释,在phpDocumentor里称为DocBlock, DocBlock是指软件开发人员编写的关于某个关键字的帮助信息,使得其他人能够通过它知道这个关键字的具体用途,如何使用。 PhpDocumentor规定一个DocBlock包含如下信息:
1. 功能简述区
2. 详细说明区
3. 标记tag
文档性注释的第一行是功能描述区,正文一般是简明扼要地说明这个类,方法或者函数的功能,功能简述的正文在生成的文档中将显示在索引区。功能描述区的内容可以通过一个空行或者 . 来结束
在功能描述区后是一个空行,接着是详细说明区,. 这部分主要是详细说明你的API的功能

凌众科技专业提供服务器租用、服务器托管、企业邮局、虚拟主机等服务,公司网站:http://www.lingzhong.cn 为了给广大客户了解更多的技术信息,本技术文章收集来源于网络,凌众科技尊重文章作者的版权,如果有涉及你的版权有必要删除你的文章,请和我们联系。以上信息与文章正文是不可分割的一部分,如果您要转载本文章,请保留以上信息,谢谢!

分享到: 更多

Copyright ©1999-2011 厦门凌众科技有限公司 厦门优通互联科技开发有限公司 All rights reserved

地址(ADD):厦门软件园二期望海路63号701E(东南融通旁) 邮编(ZIP):361008

电话:0592-5908028 传真:0592-5908039 咨询信箱:web@lingzhong.cn 咨询OICQ:173723134

《中华人民共和国增值电信业务经营许可证》闽B2-20100024  ICP备案:闽ICP备05037997号