PHP代码文档规范及phpDoc指南-共享版

PHP文档规范及phpDoc指南

目录

1概述 (3)

2PHPDoc/ phpDocumentor (3)

2.1什么是PHPDoc/phpDocumentor (3)

2.2phpDocumentor1和phpDocumentor2 (5)

2.3phpDocumentor安装 (5)

2.3.1pear安装 (5)

2.3.2phpDocumentor安装 (6)

3使用phpDocumentor生成文档 (6)

3.1phpDocumentor使用说明 (6)

3.2生成指定目录下的文档 (6)

3.3生成指定文件的文档 (6)

3.4指定文档标题 (7)

4PHP注释规范 (7)

4.1需要特别注意的地方 (7)

4.2文件、类注释 (8)

4.3方法注释 (8)

4.4常用tag标签 (9)

4.4.1常用tag列表 (9)

4.4.2@param变量类型列表 (9)

4.5常用的嵌入式{@tag }用法 (10)

4.5.1{@link}用法 (10)

4.5.2{@source}用法 (10)

4.5.3其他inline tag (11)

4.6用法 (11)

5参考资料 (12)

1概述

对于一个开发人员，文档总是最感到头疼的事情之一。而且，很可能你对待文档会采取截然不同的2种态度：

●当你使用别人的代码库的时候，最希望得到的是它的技术文档，尤其是当时间很紧，而你又不得不硬

着头皮去读那些生涩的代码的时候。

●当写你自己的程序的时候，最不希望做的事情却是给它编写专门的技术文档，你会以种种理由给自己

开脱：我的代码已经足够清晰了，完全不用再为它重新编写文档了……

为了解决这个问题，文档工具由此产生。按照规范格式编写代码注释，当代码写完了，技术文档也就完成了。良好的代码注释不仅能够帮助开发人员在编写代码时缕清思路，尽可能避免逻辑bug，而且规范的代码注释还能够使用文档工具直接生成API手册。

2PHPDoc/ phpDocumentor

2.1什么是PHPDoc/phpDocumentor

PHPDoc（现在项目名改为了phpDocumentor）是PEAR下面的一个非常优秀的模块，它的目标是实现类似javadoc的功能，可以为你的代码快速生成具有相互参照，索引等功能的API文档。

目前PHPDoc有3个主要的版本：

●PHPDoc：此版本最高到 1.0beta，已经停止维护，升级为phpDocumentor，PHPDoc的官网是

，有兴趣的话可以看看。此版本生成的文档格式如下图：

●phpDocumentor1：此版本最高到1.4.4，已经升级到phpDocumentor2，目前网上大部分的PHP开源项目都

是由此版本工具生成的API手册。官网：，此版本生成的文档格式如下图：

●phpDocumentor2：此版本还在升级维护中，目前最高版本是2.0.0alpha1。官网：，

此版本生成的文档格式如下图：

2.2phpDocumentor1和phpDocumentor2

因为最初的版本PHPDoc早已停止维护和升级，本文不再介绍和使用。phpDocumentor从1.4.4直接升到了phpDocumentor2，2比较于1做了如下改变：

●High performance：更高的性能。优化后的phpDocumentor生成同一个项目的文档，比前一版本最高节省

90秒。

●Template System：提供了非常灵活的模板系统，用户可以订制自己的API手册样式。而且也修正了1.4.4

非常讨厌的默认iso-8859-1编码，改成了默认utf-8。

●Reports & Charts：可以生成开发人员可能感兴趣的图标和报告，如类的继承关系、接口实现拓扑图，TODO

就列表等。

●Plugins：增加了以AoP模式实现的的插件功能，开发人员可以开发或重写自己的tag解释方法。

在安装和使用上，phpDocumentor1和phpDocumentor2基本一样，所以下文就统一以phpDocumentor说明。（因为phpDocumentor2的默认responsive模板生成的文档实在不太好看和不习惯，而且phpDocumentor2的新特性大多都用不上，所以笔者现在用的是能够生成php.net上PHP手册样式的phpDocumentor1.4.4）

2.3phpDocumentor安装

2.3.1pear安装

因为phpDocumentor是PEAR的一个模块，虽然phpDocumentor也支持单独下载使用，但最后以PEAR模块安装。所以如果PHP没有安装PEAR，需要先安装PEAR：

Mac OS X：

2.3.2phpDocumentor安装

●phpDocumentor1.4.4

安装要求：PHP version 4.1.0或以上

说明：phpDocumentor1.4.4比较讨厌的地方是文档的tpl模板默认编码是iso-8859-1，而不是常用的utf-8，如果不修改的话可能会产生中文乱码的问题。修改默认编码方法如下：

找到PEAR的安装目录，以笔者的电脑为例，PEAR的安装目录是：/opt/local/lib/php/pear

●phpDocumentor2

安装要求：PHP 5.2.6或以上，最好安装有XSL和Graphviz扩展。如果需要生成PDF格式的文档，还需要安装wkhtmltopdf扩展。

3使用phpDocumentor生成文档

3.1phpDocumentor使用说明

使用phpdoc –h命令可以产看帮助手册，本文不再详述。

3.2生成指定目录下的文档

3.3生成指定文件的文档

3.4指定文档标题

4PHP注释规范

4.1需要特别注意的地方

●需要生成文档的注释必须是以“/**”开头，以“*/”结尾。主流的IDE开发工具（如Eclipse，Zend）会

用不同的颜色来区分下面的几种注释。

●

●

一般以“/*”开头，而public方法以“/**”开头。

4.2文件、类注释

4.3方法注释

4.4常用tag标签

4.4.1常用tag列表

特别说明；

●@version：如果代码版本控制工具使用的是CVS，可以设置成“@version$Id: Exp $”，CVS在提交代码时

会自动填充文件的版本信息

●@see：当某些注释说明已经写过不想再重复写，或有关联的方法或类需要参见，此时用到@see

4.4.2@param变量类型列表

@param 标签需要指定参数类型，可以使用的类型如下：

●string 该参数是一个字符型变量。

●array 该参数是一个数组。

●int该参数是一个数值型，同integer

●integer 该参数是一个数值型。

●integer (octal) 该参数是一个数值型PHP参考手册，并且是按照八进制方式存放。

●integer (hexadecimal) 该参数是一个数值型，并且是按照十六进制方式存放。

●boolean 该参数是一个布尔型。

●mixed 该参数的类型是可变的，可以上面几种类型的组合。不过，在随后的说明中一般要说明可以接受的

变量的类型。

●void 无返回值，只用于@return标签，如@return void

以上类型同样适用于@property和@return

4.5常用的嵌入式{@tag }用法

嵌入式{@tag }（即inline tag）是在写注释文字段时，需要在文字段中加入链接或锚点，此时用到嵌入式tag。

4.5.1{@link}用法

在写注释文字段时需要加一些URL链接或是锚点，在生成的文档中用户可以通过鼠标点击进入这个链接或锚点，或是有关联的方法或类需要参见，此时用到{@link}。

格式如下：

{@link URL [description]}

{@link element [description]}

举例：

4.5.2{@source}用法

当需要在文档中显示具体的实现代码时，可以使用此标签。格式如下：

●显示该方法或类的所有代码：{@source}

●显示从指定行开始到方法或类的结尾代码：{@source startline}

●显示从指定行开始，到指定的行数结束的代码：{@source startline number_of_lines}

* {@source }

* displays without a break in the flow

*/

function element($pages)

{

if (empty($pages))

{

die("ERROR: nothing parsed");

}

}

相当于===》

/**

* Text with an inline source tag:

*

*

* function element($pages)

* {

* if (empty($pages))

* {

* die("ERROR: nothing parsed");

* }

* }

*

* displays without a break in the flow

*/

当然，如果不用此标签也可以直接使用标记，具体说明见下文。

4.5.3其他inline tag

其他的不太常用，具体参见官方文档：

4.6用法

标签的主要作用是为了显示代码段示例。当然，如果有大段的注释文本，而又懒得去加

等HTML标签进行换行美化，也可以使用此标签。

5参考资料

1、

2、

（编辑：财气旺网 - 财气网）

【声明】本站内容均来自网络，其相关言论仅代表作者个人观点，不代表本站立场。若无意侵犯到您的权利，请及时与联系站长删除相关内容!