探讨:如何使用PhpDocumentor生成文档


Posted in PHP onJune 25, 2013

命令行方式:

在phpDocumentor所在目录下,输入phpdoc ?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。
给php代码添加规范的注释

PHPDocument是从你的源代码的注释中生成文档,因此在给你的程序做注释的过程,也就是你编制文档的过程。

从这一点上讲,PHPdoc促使你要养成良好的编程习惯,尽量使用规范,清晰文字为你的程序做注释,同时多多少少也避免了事后编制文档和文档的更新不同步的一些问题。

在phpdocumentor中,注释分为文档性注释和非文档性注释。

所谓文档性注释,是那些放在特定关键字前面的多行注释,特定关键字是指能够被phpdoc分析的关键字,例如class,var等,具体的可参加附录1.

那些没有在关键字前面或者不规范的注释就称作非文档性注释,这些注释将不会被phpdoc所分析,也不会出现在你产生的api文当中。

如何书写文档性注释:

所有的文档性注释都是由/**开始的一个多行注释,在phpDocumentor里称为DocBlock, DocBlock是指软件开发人员编写的关于某个关键字的帮助信息,使得其他人能够通过它知道这个关键字的具体用途,如何使用。PhpDocumentor规定一个DocBlock包含如下信息:
1. 功能简述区
2. 详细说明区
3. 标记tag

文档性注释的第一行是功能描述区,正文一般是简明扼要地说明这个类,方法或者函数的功能,功能简述的正文在生成的文档中将显示在索引区。功能描述区的内容可以通过一个空行或者 . 来结束

在功能描述区后是一个空行,接着是详细说明区,. 这部分主要是详细说明你的API的功能,用途,如果可能,也可以有用法举例等等。在这部分,你应该着重阐明你的API函数或者方法的通常的用途,用法,并且指明是否是跨平台的(如果涉及到),对于和平台相关的信息,你要和那些通用的信息区别对待,通常的做法是另起一行,然后写出在某个特定平台上的注意事项或者是特别的信息,这些信息应该足够,以便你的读者能够编写相应的测试信息,比如边界条件,参数范围,断点等等。

之后同样是一个空白行,然后是文档的标记tag,指明一些技术上的信息,主要是最主要的是调用参数类型,返回值极其类型,继承关系,相关方法/函数等等。

文档注释中还可以使用例如<b> <code>这样的标签,详细介绍请参考附录二。
一个文档注释的例子
/**
* 函数add,实现两个数的加法
*
* 一个简单的加法计算,函数接受两个数a、b,返回他们的和c
*
* @param int 加数
* @param int 被加数
* @return integer
*/
function Add($a, $b)
{
return $a+$b;
}

生成文档如下:
Add
integer Add( int $a, int $b)
[line 45]

函数add,实现两个数的加法
Constants 一个简单的加法计算,函数接受两个数a、b,返回他们的和c
Parameters
• int $a - 加数
• int $b - 被加数
文档标记:

文档标记的使用范围是指该标记可以用来修饰的关键字,或其他文档标记。

所有的文档标记都是在每一行的 * 后面以@开头。如果在一段话的中间出来@的标记,这个标记将会被当做普通内容而被忽略掉。
@access

使用范围:class,function,var,define,module

该标记用于指明关键字的存取权限:private、public或proteced
@author

指明作者
@copyright

使用范围:class,function,var,define,module,use

指明版权信息
@deprecated

使用范围:class,function,var,define,module,constent,global,include

指明不用或者废弃的关键字
@example

该标记用于解析一段文件内容,并将他们高亮显示。Phpdoc会试图从该标记给的文件路径中读取文件内容
@const

使用范围:define

用来指明php中define的常量
@final

使用范围:class,function,var

指明关键字是一个最终的类、方法、属性,禁止派生、修改。
@filesource

和example类似,只不过该标记将直接读取当前解析的php文件的内容并显示。
@global

指明在此函数中引用的全局变量
@ingore

用于在文档中忽略指定的关键字
@license

相当于html标签中的<a>,首先是URL,接着是要显示的内容

例如<a href=”http://www.baidu.com”>百度</a>

可以写作 @license http://www.baidu.com 百度
@link

类似于license

但还可以通过link指到文档中的任何一个关键字
@name

为关键字指定一个别名。
@package

使用范围:页面级别的-> define,function,include

类级别的->class,var,methods

用于逻辑上将一个或几个关键字分到一组。
@abstrcut

说明当前类是一个抽象类
@param

指明一个函数的参数
@return

指明一个方法或函数的返回指
@static

指明关建字是静态的。
@var

指明变量类型
@version

指明版本信息
@todo

指明应该改进或没有实现的地方
@throws

指明此函数可能抛出的错误异常,极其发生的情况

上面提到过,普通的文档标记标记必须在每行的开头以@标记,除此之外,还有一种标记叫做inline tag,用{@}表示,具体包括以下几种:
{@link}

用法同@link
{@source}
显示一段函数或方法的内容

一些注释规范
a.注释必须是
/**
* XXXXXXX
*/

的形式
b.对于引用了全局变量的函数,必须使用glboal标记。
c.对于变量,必须用var标记其类型(int,string,bool...)
d.函数必须通过param和return标记指明其参数和返回值
e.对于出现两次或两次以上的关键字,要通过ingore忽略掉多余的,只保留一个即可
f.调用了其他函数或类的地方,要使用link或其他标记链接到相应的部分,便于文档的阅读。
g.必要的地方使用非文档性注释,提高代码易读性。
h.描述性内容尽量简明扼要,尽可能使用短语而非句子。
i.全局变量,静态变量和常量必须用相应标记说明

总结
phpDocumentor是一个非常强大的文档自动生成工具,利用它可以帮助我们编写规范的注释,生成易于理解,结构清晰的文档,对我们的代码升级,维护,移交等都有非常大的帮助。
关于phpDocumentor更为详细的说明,可以到它的官方网站

两个例子:
实例一
实例二

PHP 相关文章推荐
PHP 编写的 25个游戏脚本
May 11 PHP
php网站来路获取代码(针对搜索引擎)
Jun 08 PHP
PHP中对用户身份认证实现两种方法
Jun 04 PHP
多个PHP中文字符串截取函数
Nov 12 PHP
PHP中auto_prepend_file与auto_append_file用法实例分析
Sep 22 PHP
php中使用gd库实现下载网页中所有图片
May 12 PHP
PHP实现简单实用的分页类代码
Apr 08 PHP
PHP实现bitmap位图排序与求交集的方法
Jul 28 PHP
php自定义函数实现二维数组按指定key排序的方法
Sep 29 PHP
php创建图像具体步骤
Mar 13 PHP
微信公众平台开发教程④ ThinkPHP框架下微信支付功能图文详解
Apr 10 PHP
PHP检测一个数组有没有定义的方法步骤
Jul 20 PHP
关于PHPDocument 代码注释规范的总结
Jun 25 #PHP
解析php中获取系统信息的方法
Jun 25 #PHP
解析PHP对现有搜索引擎的调用
Jun 25 #PHP
手把手教你打印出PDF(关于fpdf的简单应用)
Jun 25 #PHP
解析如何修改phpmyadmin中的默认登陆超时时间
Jun 25 #PHP
关于Sphinx创建全文检索的索引介绍
Jun 25 #PHP
使用Sphinx对索引进行搜索
Jun 25 #PHP
You might like
ThinkPHP入口文件设置及相关注意事项分析
2014/12/05 PHP
实现PHP搜索加分页
2016/10/12 PHP
PHP快速排序算法实现的原理及代码详解
2019/04/03 PHP
jQuery EasyUI API 中文文档 可调整尺寸
2011/09/29 Javascript
js substr支持中文截取函数代码(中文是双字节)
2013/04/17 Javascript
JavaScript对象和字串之间的转换实例探讨
2013/04/21 Javascript
JavaScript中的运算符种类及其规则介绍
2013/09/26 Javascript
用jquery写的菜单从左往右滑动出现
2014/04/11 Javascript
javascript实现在某个元素上阻止鼠标右键事件的方法和实例
2014/08/12 Javascript
JavaScript中String.match()方法的使用详解
2015/06/06 Javascript
js日期插件dateHelp获取本月、三个月、今年的日期
2016/03/07 Javascript
jQuery中队列queue()函数的实例教程
2016/05/03 Javascript
javascript 动态脚本添加的简单方法
2016/10/11 Javascript
vue制作加载更多功能的正确打开方式
2016/10/12 Javascript
jQuery自定义图片上传插件实例代码
2017/04/04 jQuery
基于webpack 实用配置方法总结
2017/09/28 Javascript
select获取下拉框的值 下拉框默认选中方法
2018/02/28 Javascript
vue项目中使用tinymce编辑器的步骤详解
2018/09/11 Javascript
nodemon实现Typescript项目热更新的示例代码
2019/11/19 Javascript
用jQuery实现抽奖程序
2020/04/12 jQuery
[46:02]DOTA2上海特级锦标赛D组资格赛#2 Liquid VS VP第二局
2016/02/28 DOTA
Python中的Matplotlib模块入门教程
2015/04/15 Python
python实现rsa加密实例详解
2017/07/19 Python
python 递归遍历文件夹,并打印满足条件的文件路径实例
2017/08/30 Python
python卸载后再次安装遇到的问题解决
2019/07/10 Python
python数据类型强制转换实例详解
2020/06/22 Python
旅游专业职业生涯规划范文
2014/01/13 职场文书
转让协议书范本
2014/04/15 职场文书
企业群众路线教育实践活动心得体会
2014/11/03 职场文书
2014年新教师工作总结
2014/11/08 职场文书
委托函范文
2015/01/29 职场文书
高一军训决心书
2015/02/05 职场文书
2015年文员个人工作总结
2015/04/09 职场文书
走进毛泽东观后感
2015/06/04 职场文书
导师鉴定意见
2015/06/05 职场文书
低版本Druid连接池+MySQL驱动8.0导致线程阻塞、性能受限
2021/07/01 MySQL