脚本宝典收集整理的这篇文章主要介绍了PDP Document 代码注释规范,脚本宝典觉得挺不错的,现在分享给大家,也给大家做个参考。
1. 什么是PHPDocumentor ?
PHPDocumentor是
一个用
PHP写的工具,对于有规范注释的
PHP程序,它能够
快速生成具有相互参照,索引等
功能的
api文档。老的版本是
PHPdoc,从1.3.0
开始,更名为
PHPDocumentor,新的版本
加上了对
PHP5语法的
支持,同时,可以通过在客户端浏览器上操作
生成文档,文档可以转换为P
DF,HT
ML,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:fr
ames: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。
PHPDocument是从你的源
代码的注释中
生成文档,因此在给你的程序做注释的过程,也就是你编制文档的过程。
从这
一点上讲,
PHPdoc促使你要养成良好的编程习惯,尽量使用规范,清晰
文字为你的程序做注释,同时多多少少也避免了事后编制文档和文档的更新不同步的一些问题。
在
PHPdocumentor中,注释分为文档性注释和非文档性注释。
所谓文档性注释,是那些放在特定关键字前面的多行注释,特定关键字是指能够被
PHPdoc分析的关键字,例如class,
VAR等,具体的可参加附录1.
那些没有在关键字前面
或者不规范的注释就称作非文档性注释,这些注释将不会被
PHPdoc所分析,也不会出现在你产生的api文当中。
3.2如何书写文档性注释:
所有的文档性注释都是由/**开始的
一个多行注释,在
PHPDocumentor里称为DocBlock,DocBlock是指软件开发人员编写的关于某个关键字的帮助信息,使得其他人能够通过它
知道这个关键字的具体
用途,如何使用。
PHPDocumentor规定
一个DocBlock包含如下信息:
1.
功能简述区
2. 详细说明区
3.
标记tag
文档性注释的第一行是
功能描述区,正文一般是
简明扼要地说明这个类,
方法或者
函数的
功能,
功能简述的正文在
生成的文档中将
显示在索引区。
功能描述区的
内容可以通过
一个空行或者 . 来结束
在
功能描述区后是
一个空行,接着是详细说明区,. 这部分主要是详细说明你的API的
功能,用途,如果可能,也可以有
用法举例
等等。
在这部分,你
应该着重阐明你的API
函数或者
方法的通常的用途,
用法,并且指明
是否是跨平台的(如果涉及到),对于和平台相关的信息,你要和那些通用的信息区别对待,通常的做法是另起一行,然后写出在某个特定平台上的注意
事项或者是特别的信息,这些信息应该足够,以便你的读者能够编写相应的测试信息,比如边界条件,参数范围,断点等等。
之后同样是
一个空白行,然后是文档的
标记tag,指明一些技
术上的信息,主要是最主要的是
调用参数类型,返回值极其类型,继承关系,相关
方法/
函数等等。
关于文档
标记,详细的请参考第四节:文档
标记。
文档注释中还可以使用例如
这样的标签,详细介绍请参考附录二。
下面是一个文档注释的例子
代码如下:
脚本宝典总结
以上是脚本宝典为你收集整理的PDP Document 代码注释规范全部内容,希望文章能够帮你解决PDP Document 代码注释规范所遇到的问题。
如果觉得脚本宝典网站内容还不错,欢迎将脚本宝典推荐好友。
本图文内容来源于网友网络收集整理提供,作为学习参考使用,版权属于原作者。
如您有任何意见或建议可联系处理。小编QQ:384754419,请注明来意。