探讨:如何使用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开发中常用的8个小技巧
Aug 27 PHP
PHP常用函数小技巧
Sep 11 PHP
php下获取Discuz论坛登录用户名、用户组、用户ID等信息的实现代码
Dec 29 PHP
Windows中使用计划任务自动执行PHP程序实例
May 09 PHP
PHP的拦截器实例分析
Nov 03 PHP
laravel 5 实现模板主题功能
Mar 02 PHP
PHP生成各种常见验证码和Ajax验证过程
Jan 10 PHP
Laravel 5.5 的自定义验证对象/类示例代码详解
Aug 29 PHP
php读取本地json文件的实例
Mar 07 PHP
PHP simplexml_load_file()函数讲解
Feb 03 PHP
PHP iconv()函数字符编码转换的问题讲解
Mar 22 PHP
PHP基于openssl实现非对称加密代码实例
Jun 19 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
phpmyadmin的#1251问题
2006/11/25 PHP
PHP 5.0对象模型深度探索之对象复制
2008/03/27 PHP
php获取指定(访客)IP所有信息(地址、邮政编码、国家、经纬度等)的方法
2015/07/06 PHP
ASP.NET jQuery 实例3 (在TextBox里面阻止复制、剪切和粘贴事件)
2012/01/13 Javascript
HTML5之lang属性与dir属性的详解
2013/06/19 Javascript
js中window.open打开一个新的页面
2014/08/10 Javascript
php常见的页面跳转方法汇总
2015/04/15 Javascript
原生js页面滚动延迟加载图片
2015/12/20 Javascript
JavaScript数据结构与算法之集合(Set)
2016/01/29 Javascript
AngularJS自动表单验证
2016/02/01 Javascript
设计模式中的组合模式在JavaScript程序构建中的使用
2016/05/18 Javascript
移动适配的几种方案(三种方案)
2016/11/25 Javascript
微信小程序 tabs选项卡效果的实现
2017/01/05 Javascript
WebPack基础知识详解
2017/01/16 Javascript
js实现简单的选项卡效果
2017/02/23 Javascript
JQuery模拟实现网页中自定义鼠标右键菜单功能
2018/11/14 jQuery
小程序如何在不同设备上自适应生成海报的实现方法
2019/08/20 Javascript
JS正则表达式验证密码强度
2020/03/18 Javascript
vue组件入门知识全梳理
2020/09/21 Javascript
python中List的sort方法指南
2014/09/01 Python
详谈Python高阶函数与函数装饰器(推荐)
2017/09/30 Python
Python中的上下文管理器和with语句的使用
2018/04/17 Python
Python 使用PIL numpy 实现拼接图片的示例
2018/05/08 Python
python3爬取数据至mysql的方法
2018/06/26 Python
Django异步任务之Celery的基本使用
2019/03/23 Python
Python编译成.so文件进行加密后调用的实现
2019/12/23 Python
python利用faker库批量生成测试数据
2020/10/15 Python
python爬虫中的url下载器用法详解
2020/11/30 Python
计算机专业推荐信范文
2013/11/20 职场文书
公务员诚信承诺书
2014/05/26 职场文书
三严三实对照检查材料
2014/08/25 职场文书
暑期家教宣传单
2015/07/14 职场文书
创业计划书之花店
2019/09/20 职场文书
经典人生语录分享:不畏将来,不念过去,笑对当下
2019/12/12 职场文书
MySQL之select、distinct、limit的使用
2021/11/11 MySQL
Python自动化工具之实现Excel转Markdown表格
2022/04/08 Python