2001 年 5 月 01 日
对于一个开发人员，文档总是最感到头疼的事情之一。而且，很可能你对待文档会采取截然不同的2种态度：
当你使用别人的代码库的时候，最希望得到的是它的技术文档，尤其是当时间很紧，而你又不得不硬着头皮去读那些生涩的代码的时候。
当写你自己的程序的时候，最不希望做的事情却是给它编写专门的技术文档，你会以种种理由给自己开脱：我的代码已经足够清晰了，完全不用再为它重新编写文档了……
也许是为了缓解这种矛盾，有很多工具可以帮助你，通过从源代码中抽取相应的注释，可以自动生成相应的api文档。java中的javadoc,perl中的pod2man。相比之下，php以前似乎缺乏相应的工具，不过，随着phpdoc的不断完善，这种局面已经大大改观。
在第一篇pear的编码规则中有一条，pear程序中的注释应该能够被phpdoc转换。由此可见，phpdoc在pear中的作用可不小。今天，我们将详细讨论phpdoc，这个优秀的pear程序。
PHPDoc是PEAR下面的一个非常优秀的模块，它的目标是实现类似javadoc的功能，可以为你的代码快速生成具有相互参照,索引等功能的API文档。如果你使用过javadoc生成的文档(如jdk的文档），你会非常清楚，如果你没有用过，那么下面是一个phpdoc生成它自己的文档页面的截图：
从图上可以知道，phpdoc生成的文档和JAVADOC很相似，它有多种的索引方式：
Packageindex:这是按照模块来索引
Classtree:这是按照你的php类的继承关系，可以生成一个树状的索引
Modulegroups:这是按照模块划分
Elementlist:这是你的所有元素（类，方法，过程/函数，变量）的字母顺序的索引
由于phpdoc本身也是符合pear的应用程序，我们首先了解一下它的结构。phpdoc是全部采用OOP的思想来编写的，这也是PEAR所推荐的方式,phpdoc的工作原理：
1. phpdoc扫描指定目录下面的php源代码，扫描其中的关键字，截取需要分析的注释，然后分析注释中的专用的tag，生成xml文件，接着根据已经分析完的类和模块的信息，建立相应的索引，生成xml文件
2. 对于生成的xml文件，使用定制的模板输出为html文件。
从设计上来说，phpdoc使用了2个超类：PhpdocObject和PhpdocError。这是整个PHPDOC的基本类，这种方式也是PEAR所推荐的，也就是说当你编写你自己的应用框架的时候，最好能够有一个基本的超类，而其他的子类或者是功能类都有一个共同的祖先。在扫描源代码过程中，PHPDOC使用的是类似GREP的形式，并没有象我们通常想的那样，使用正则表达式来实现，根据作者的解释，他曾经尝试过使用正则表达式，但是资源的占用和处理速度都很难令人满意，因此采用了这种非常规的形式，具体的实现有兴趣的读者可以参看源代码。我认为PHPDOC令人满意的另一方面是其分析结果是以XML形式保存的，这样就意味着其他的应用程序很容易可以共享这个数据，同时PHPDCO也提供了相应的接口，你可以实现这个接口，把API文档生成其他的形式，比如PDF，LATEX，WORD等等。目前，PHPDOC的分析结果可以以HTML形式表现，以后可能会有更多的形式。即使是HTML形式，由于使用了模板机制（他使用了PEAR的IT和ITX模块来实现），你可以很方便地定制成你自己需要的风格，
PHPDoc是从你的源代码的注释中生成文档，因此在给你的程序做注释的过程，也就是你编制文档的过程。
从这一点上讲，PHPdoc促使你要养成良好的编程习惯，尽量使用规范，清晰文字为你的程序做注释，同时多多少少也避免了事后编制文档和文档的更新不同步的一些问题。
编制符合PHPDoc规范的注释是非常重要的，掌握了这一点，基本上就可以利用PHPDoc为你工作了。
注释在PHPDoc中分为文档注释和非文档注释
文档注释实际上是一些特殊形式的多行注释，一般是放在你需要注释的特定的关键字(这些关键字是指将会被phpdoc分析的那些关键字，相关的关键字列表请参看后面第4节的说明）前面。下面是一个文档注释的例子：
/**
* Common base class of all phpdoc classes （简述，用在索引列表中）
*
* As a kind of common base class PhpdocObject holds
* configuration values (e.g. error handling) and debugging
* methods (e.g. introspection()). It does not have a constructor,
* so you can always inheritig Phpdoc classes from this
* class without any trouble. （详细的功能描述）
*
* @author Ulf Wendel
* @version$Id: PhpdocObject.php,v 1.3 2001/02/18 15:29:29 uw Exp $
* @packagePHPDoc （文档标记）
*/
class PhpdocObject {
.....
}
|
以上的文档注释将会生成如下的文档：
<b>PhpdocObject</b>
PhpdocObject
Common base class of all phpdoc classes
<b>private class PhpdocObject </b>
Common base class of all phpdoc classes
As a kind of common base class PhpdocObject holdsconfiguration values (e.g. error
handling) and debuggingmethods (e.g. introspection()). It does not have a
constructor,so you can always inheritig Phpdoc classes from thisclass without any trouble.
Authors Ulf Wendel <ulf.wendel@phpdoc.de>
Version $Id: PhpdocObject.php,v 1.3 2001/02/18 15:29:29 uw Exp $
|
如果你的注释没有放在那些phpdoc指定的关键字前面，那么phpdoc认为你所作的这些注释是属于非文档注释，将不会被phpdoc所分析，也不会出现在你产生的api文当中。
从3.1 我们可以看到，一个文档性的注释，是由3个部分组成的，分别是：功能简述区，功能详细说明区，文档标记区。
首先，第一行是一个注释开始的标志"/**"，然后是回车，从第2行开始就是功能简述区，功能简述区是以缩进的"*"开始的，在简述的正文和这个"*"号之间用空格分隔（注意，在文档中，都是以*开始，并且这些*保持对齐的缩进格式）。功能简述的正文一般是简明扼要地说明这个类，方法或者函数的功能，功能简述的正文在生成的文档中将显示在索引区。
在功能简述区后面是一个空的注释行，用来分割简述区和详细说明区。功能详细说明区也是以缩进的'*"来引导的，这部分主要是详细说明你的API的功能，用途，如果可能，也可以有用法举例等等。在这部分，你应该着重阐明你的API函数或者方法的通常的用途，用法，并且指明是否是跨平台的（如果涉及到），对于和平台相关的信息，你要和那些通用的信息区别对待，通常的做法是另起一行，然后写出在某个特定平台上的注意事项或者是特别的信息，这些信息应该足够，以便你的读者能够编写相应的测试信息，比如边界条件，参数范围，断点等等。
在功能详细说明区后面，是空白的注释行，然后是文档标记区，你可以在这些书写相关的文档标记（这些文档标记的用法请参考后面的第4节），指明一些技术上的细节信息，最主要的是调用参数类型，返回值极其类型，继承关系，相关方法/函数等等。多个文档标记应该使用相同的缩进，组成一个"标记块"，便于阅读和分析。
在文档标记区下面的一行就是注释结束行"*/",注意，在注释结束标记*/后面应该直接跟一个回车，不要另外附加其他的东西，否则可能造成PHPDOC分析出错。
以上就是书写一个文档性注释的基本方法，下面我们讨论一下书写文档时的规范和技巧。
在你描述你的代码的用途或者是功能的时候，最好能够遵循大多数人的习惯，通俗地讲就是"你告诉我的信息正是我想要知道的"。为此，这里将介绍一些书写文档注释的技巧和规范，希望能够对你有所帮助：
1. 使用 <code> 来标志关键字和命名及相关的代码。如果在文档中需要引用一些关键字，变量名，或者是你要给出一些代码的例子，那么你最好使用<code></code>来将这些关键字，变量名，代码片段和你的文档分隔开，这样，读者阅读的时候，将会知道，这些将是运行的代码，关键字而不是你的描述性的语言。
2. 使用简单，明确的语言，避免冗长，复杂，晦涩的长句来描述。尤其是在功能简述，参数说明等索引部分中，尽量使用简单明白的语言揭示主要的信息，把其他的细节放在详细说明部分去阐述。如果你使用英语，建议使用短语而不一定是句子。
3. 如果使用英语，建议使用第3人称单数的形式来说明
4. 在给方法，函数说明的时候，你需要说明的是这个方法"作了什么"，而不是"怎么做"。因此，建议你的说明是以动词开始，比如"返回记录数"，"删除给定的记录"等等。
5. 当你引用的某个对象或者变量是从当前的类中建立的，那么使用 "this" 代替 "the" 来指代那个对象或者是变量
6. 避免空话，废话，对于你所要给出的API，在你的API后面要有它的功能描述，是其能够"自成文档"。所谓的空话，废话是指，你的描述不是功能描述，而只是API名称的简单重复和罗列，或者是用另一个API来解释这个API，到头来，你的读者也不知道你所要表达的内容实质。你的描述，应该是那些从你的类名，方法名，或者是函数名看不到的补充的信息，而不是把你的API名称再重复一遍。很多人可能很多人（包括我）不知不觉中就犯了这个错误，下面是一个例子：
/**
* 设置用户记录集
*
* @param text给定的表名
*/
function set_user_record($table) {
|
你从上面这段注释中能够知道什么？因此，这段注释实际上是废话，因为你从函数名称上是可以看出的，下面是改进后的：
/**
* 打开系统用户表并设置为当前用户记录集，此记录集将用于随后相关用户数据更新操作的缺省记录集。如果失败则抛出一个数据库错误。
*
* @param text要打开的系统用户表的表名。
*/
function set_user_record($table) {
|
-
适当地使用链接。为你文档中引用的API名称（包括你的其他类及方法，PHP的函数等）添加适当的链接是很受欢迎的：你可以使用@link标记来添加到相关的API的链接，不过，你没有必要为文档中引用的所有的API都添加连接，这样会很不美观，这里有一个简单的标准：如果用户在这个地方看到某个API，确实希望要去点击以便获取更多信息，这样有助于他们去理解你的文档，并且即使添加了链接，只在它第一出现的是时候添加，没有必要重复添加相同的LINK。
-
由于PHPDOC的功能限制，一个PHP文件只定义一个类或模块，不要把类和模块的定义放在同一个文件里，否则PHPDOC可能无法工作，至少目前版本是这样。如果你的框架使用OOP来构建，应避免同时使用模块或模块组；同时应该仔细规划你的应用结构，你的应用框架应该是一个类似树型的结构，顶层的分支不要太多，例如你可以设计2个超类，分别是作为正常应用和错误处理的超类，其余的都从这2个类派生出来。
class 、function 、var 、include (include_once, require, require_once) 、define
在以上这些关键字前面所做的注释，都被认为是文档性注释。
说明：使用范围是指该标记可以用来修饰的关键字，或其他文档标记
@abstract 使用范围：class, function, var
说明当前类是一个抽象类。
注释：从PHP语言角度来说，它并不象JAVA，C++那样，支持抽象类这个概念。也没有相应的关键字来修饰某个类是抽象类。由于PHPDOC实际上大部分是借鉴了JAVADOC的做法，因此很多文档标记也是直接从JAVADOC中沿袭过来，如abstract,access,final等等。虽然这些特性没有从语言级别得到支持，不过从使用者角度来遵循这些特性，仍是值得推荐的。
举例：
/**
* 这是一个绘五星图案的抽象类.
* @abstract
*/
class paint_start {
/**
* 绘制数量
* @abstract
*/
var $number;
/**
* 绘制五星图案
* @abstract
*/
function paint() {
;
}
}
|
@access (public|private) 使用范围：class, function, var, define, module
指明这个变量、类、函数/方法的存取权限。如果你的函数是内部使用，你应该指明它为private,这样的好处是，即使PHP不能阻止其他的人使用你的私有数据，但是至少你向你的用户传达这样的信息，这是一个私有的函数，因此不保证在将来的版本中仍存在；对于使用者而言，表示为@private的数据和方法，你不应该直接使用，即使你可以这样做。
举例：
/**
* 这是一个绘五星图案的抽象类.
* @abstract
* @access public
*/
class paint_start {
/**
* 绘制数量
font-size: 9pt; color: black
分享到：
Global site tag (gtag.js) - Google Analytics
|
相关推荐
PEAR, the PHP Extension and Application Repository, is a bountiful resource for any PHP developer. Within its confines lie the tools that you need to do your job more quickly and efficiently. You need...
PEAR 博文链接：https://spamer.iteye.com/blog/158148
This first chapter of the book discusses how to install PEAR and how to use the PEAR package manager. It also discusses how to configure PEAR. If you’ve already been using the PEAR package manager ...
PHP核心教程 php pear php pear php pear php pear php pear php pear
下载后在PHP安装目录下建立一个Pear目录，然后解压进去，再在PHP.ini中的include_path中加入这个路径，就可以使用了。这个包是我最近才更新的，因为Pear是实时更新的，所以并不保证是最新版，有能力自己安装的朋友...
PEAR::DB::OO 是一个抽象层，用于访问面向对象范式中的数据库表。 它面向 PHP 开发人员，是用 PHP 编写的。 它建立在 PEAR 的过程数据库抽象层 (PEAR::DB) 之上——请参阅 http://pear.php.net。
:pear: Pears - 静态站点入门套件 用于快速、轻松、高效地构建静态站点的入门工具包。 :warning: 目前，Pears 处于早期发展阶段。 事情可能会破裂和改变。 :trophy: 目标使用和开发超级简单。 没有搞乱设置和配置。 ...
PHP5.4.3 下安装PEAR、PHPUnit、phpDoc2...
该模块将尝试通过包名php-pear （这也是可配置的）安装 PEAR，然后将允许通过 pear::package 函数安装 PEAR 包。 下面是一个安装默认php-pear包并升级 PEAR，然后安装 Console_Table，最后从第三方 PEAR 存储库 ...
Pear-用于物联网/嵌入式设备的WebRTC工具包 Pear是用C编写的WebRTCSDK。SDK旨在将IoT /嵌入式设备与WebRTC应用程序集成。 注意：该项目正在进行中。 当前，仅支持将H264视频流传输到浏览器。 依存关系 入门 # sudo...
Pear :: DbDeploy是一个梨软件包，用于将dbdeploy用作数据库更改管理工具。 （请参阅http://dbdeploy.com/）
:kiwi_fruit: :lemon: :pear: :strawberry: :tangerine: :pineapple: :shortcake: :cherries: :melon: :grapes: :watermelon: :green_apple: :red_apple: :banana: 介绍 用于捆绑JavaScript的最受欢迎的两个库是和...
php pear install pear安装包
不用多说了，一本pear的好书,值得下载，机不可失 不用多说了，一本pear的好书,值得下载，机不可失 不用多说了，一本pear的好书,值得下载，机不可失 不用多说了，一本pear的好书,值得下载，机不可失
php扩展包pear手册，学习php语言必备的工具之一。。
老版PHP用go-pear.php，新版用go-pear.phar 用cmd命令行下：php.exe 文件名 试一下就知道了
PHP PEAR 安装包 go-pear.phar
碰撞版本 ...使用版本号和latest标签标记新的 Github 版本。 git tag -d latest git tag latest git tag X.Y.Z 运行该文件夹中的bump_version.sh脚本。 sh bump_version.sh 3.7.2 这将创建一个新