如何文档化你的PHP类
程序员文章站
2022-04-18 17:32:20
...
你已经阅读过关于：面向对象编程可以帮助你管理你的大型web项目，并且你已经开始使用PHP来进行面向对象编程了吗？如果你已经编写了几个类应用在网站上并且你是一个有条理的人的话，那么你应该已经编写了关于它们的一些文档。但是如果你是一个象我一样的不拘小节的人，你只是会在类的源代码中加一些注释而没有别的文档。没有文档就很难记住方法的名字和它们的使用方法（参数和含义）。解决这种情况最典型的办法就是打开源代码文件，从成百上千的语句中查找。
类似Javadoc的文档
应该有一种好的方法----如果你曾经使用过Java语言，你将知道Javadoc文档系统。这个工具允许你在源代码文件注释中插入一些标记，这些标记可以被Javadoc工具进行分析以便生成一系列的HTML页面把你的类文档化。那样在编程的同时你可以开着浏览器并且可以得到类列表和带有说明的类方法的列表。在你开发web应用时，这个可以成为你的参考，提高工作效率和加快开发速度。
我的意见是维护一个作为源代码内的引用文档要比维护一个独立的文档要容易和更实用，因为这个方法更容易保持更新。否则就非常容易变得懒惰从而将对文档的更新推后到无限期（如果一定要给它加个期限，我想是一万年）。相反使用象这样的一个工具，只有一点工作量就是在你正在修改的源代码附近更新一个标记，接着运行工具再一次生成更新过的HTML页面。
一些php文档工具的预览
在对上面了解了之后，我搜索了一下哪些是可用的，并且我发现了如下一些有趣的工具：
phpSearchdoc是enzyme项目的一部分。因为enzyme 是一个巨大的项目，所以需要将其文档化。那里的开发人员已经编写了他们自已的文档系统并且他们非常慷慨地将其作为一个独立的包进行发布。得到的文档首先被写入数据库，然后可以被一些PHP脚本查看，象一个动态的web站点。
从现存的信息中将用于分析的逻辑分离出来的想法相当好，然而phpSearchdoc(版本 1.01)不具有一个真正的分析器，而是从源文件，甚至包括注释中搜索关键字。事实上，对我来说碰巧发生过在我的注释中存在'function'单词，结果分析器愚蠢地认为在这个单词后面的词就是函数的名字。更不幸的是，我不巧在同一行放了一个单引号(')，接着我试图将数据写到数据库中，mysql作出了抱怨（出错了，因为单引号在 mysql中被用于分割字符串）。
而且它的安装及运行相当困难，因为它还是一个alpha测试版。毕竟比起文档系统来说它更象是一个交叉引用生成器，正如我知道的，你不能在函数和方法中加入自已的注释。
phpxref，就象名字所指的比起一个真正 的文档系统来似乎更象是面向交叉引用的生成处理。更进一步说它更适合于正常的过程化编程而不是面向对象编程。
phpautodoc的目标是实现象Javadoc 应用于Java那样用于PHP。它看上去是满足我的文档需求的完美解决。为了试验它我不得不编译了PHP的CGI版本（我通常使用模块版本），因为生成器是用PHP编的。我可能容易地在一个Linux系统下编译和安装静态的执行程序，可以使用这些命令：
rm config.chche
make clean
./configure
make
cp php /usr/local/bin
我决定对它自已的PHP源码进行测试，并且我发现它只有部分可以工作：它只能够生成类的文档（生成整齐的格式），但是不能生成小结。我不知道是否这个只是碰巧发生在我的机器上，但是在试图生成小结时却因为core dump(内核崩溃)而停止（PHP 4.0 pl2，RedHat 6.2环境）。假如在你的机器/usr/local/bin下安装了PHP执行版本，调用它的语法是（为了得到结果我不得不给出php文件和输出目录的全路径）
./phpautodoc -o
phpdoc是一个用来维护在Web站点上的php 文件，并且它非常适合分布式开发方式。文档是从数据库中生成；在安装之后，你可以使用web界面来增加你的类将其文档化。这个的确有意思，但是它是一种低级的从源代码中分离文档的维护方法，这一点就我来说不是非常方便。
通用工具
在经受了试验所有这些工具但却得不到怎么成功的挫折之后，直到Pear Project提出了一种标准的解决方法，我发现了一个与PHP完全无关的可工作的工具在Open Source Projects at Apple站点。项目的名字是 HeaderDoc。就象站点所说的" HeaderDoc是一种从C或C++头文件的注释中生成HTML的引用文档的工具。它是用Perl编写的以便于移植。与JavaDoc 相似，它允许开发者容易地文档化他们的接口，并且将接口信息输出到HTML。"
是的，你看的没错，HeaderDoc只支持C和C++。没有其它的语言，但是它不象JavaDoc，它大部分依赖写在注释中的标记，所以只要做些小改动（我会在后面解释）就可以很好的用在PHP上。这些标记同JavaDoc很象，HeaderDoc标记的一些例子是@class，@function和@var。
文档化一个类
OK，让我们现在进入细节吧。首先让我们看一下一个类如何被文档化。
--------------------------------------------------------------------------------
/*! @class BagItem
@abstract An item in the shopping bag - it is a shopitem with quantity
@discussion A BagItem object may be constructed without previous
instantiation of neither ShopItem nor Product
*/
--------------------------------------------------------------------------------
文档化一个类。可以在左边的帧选择类的方法。
第一件需要注意的事情是用在打开注释上的风格不完全象JavaDoc注释/**(一个斜线和两个星号)，而是换成/*!(一个斜线，一个星号和一个感叹号) 。标记使用也不一样，但是它们以相似的方式工作。例如，第一个标记是@class标记，它用于文档化一个类，这个标记跟着类的名字。下一个标记是@abstract 标记，它
是一个可选的标记，用少量词语来描述一个类的含义，同时@discussion 标记是另一个可选的标记，用于进一步的讨论。当然由你来决定是在@discussion标记中描述所有的事情还是使用@abstract来处理，但是要记住，一般来说，你使用的标记越精确，结果就越好。
文档化函数或方法
成员函数或方法使用@function标记被文档化。
--------------------------------------------------------------------------------
/*! @function getItemingroup
@abstract gets a bagitem of a given group and a given position
@param groupno int - the delivery group ordinal position in the bag
@param pos int - the position of the bagitem within the group
@result Object - the BagItem in a given position of given group
or -1 if it could not be found
*/
--------------------------------------------------------------------------------
文档化一个方法。
@function标记声明了一个函数并且后面跟着函数或成员函数名。然后你可以象前面一样使用 @abstract和@discussion标记。然而还有两个额外的标记。@param标记用于描述函数的参数；第一个词假设为变量的名字，其它的则为任意的文本描述。我建议要声明想要的变量类型，尽管PHP不是一个强类型语言。 @result标记被用于描述返回值。
文档化变量
变量或类变量都使用@var标记来描述。在这个标记中，第一个词被认为是变量的名字，同时其它的则为任意的文本描述。象前面一样，我建议写出所期望的变量类型是好的做法。它也是一个文档化所有类变量的好主意。
文档化一个类变量。
--------------------------------------------------------------------------------
/*! @var idsession string - an unique session identifier */
var $idsession;
--------------------------------------------------------------------------------
最后接触
--------------------------------------------------------------------------------
/*! @header myprojectname
@abstract a virtual store to shop on mars
@discussion The difference [...]
*/
--------------------------------------------------------------------------------
@header标记用来提供一些关于被文档化的项目或类组的一般性信息。@header标记本身跟着项目的名字 ，而且可以用@abstract标记和@discussion标记来补充说明。因为类通常存在于不同的文件中（一个文件一个类，且用类的名字给文件名字是一种好的想法），你可能想知道应该将@header 标记放在什么地方。答案很让人吃惊，哪都可以。我的建议是：如果它比较长就把它放在一个独立的文件中，或如果是一个简短的说明就把它放在最重要的类的前面。
如何修改脚本用于PHP
从Apple得到的初始的HeaderDoc脚本是用于C或C++头文件的，所以要用在PHP中需要对它做一些小改动 。如果你对细节没有兴趣，你可以从这里下 载，并且跳过下面部分。
修改源程序所做的唯一的事情就是在主perl文件中，使脚本可以接受.php和.php3后缀。
--------------------------------------------------------------------------------
$ diff headerDoc2HTML.pl /usr/local/bin/headerdoc2html
195c195
---
> ($rootFileName = $filename) =~ s/.(h|i|php|php3)$//;
--------------------------------------------------------------------------------
运行脚本
在安装完脚本之后，假设你的类放在classes子目录下，并且你想将生成的文档放在docs目录下，你应该执行这个命令：
headerdoc2html -o docs classes/*.php
不幸的是如果存在多个PHP文件，这个脚本有一个坏习惯就是将那些文件分割到不同的目录中去，使得在类的文档中浏览变得很困难。而且因为初始的脚本是为C/C++头文件所写的（头文件中只有类和函数的声明而没有他们的定义），脚本会将函数名下的所有代码输出，直到碰到";"，所以典型的就是代码的第一行。
但是在你好不容易读到现在却感到绝望之前，放松，因为我写了一段简单的脚本来解决这两个问题。
--------------------------------------------------------------------------------
cat classes/*.php | sed 's/ *{/;#{/g' | tr "#" "
" > docs/all.php
headerdoc2html -o docs docs/all.php
rm docs/all.php
--------------------------------------------------------------------------------
如果你想知道为什么我在这里使用tr命令而不是都用sed来做，原因就是用在仍然用在RedHat 6.2上的sed 3.02版本不处理换行符。应该替换成新的版本sed 3.02a。如果你对sed感兴趣，可以看SED FAQ。
祝你的文档化工作好运！
类似Javadoc的文档
应该有一种好的方法----如果你曾经使用过Java语言，你将知道Javadoc文档系统。这个工具允许你在源代码文件注释中插入一些标记，这些标记可以被Javadoc工具进行分析以便生成一系列的HTML页面把你的类文档化。那样在编程的同时你可以开着浏览器并且可以得到类列表和带有说明的类方法的列表。在你开发web应用时，这个可以成为你的参考，提高工作效率和加快开发速度。
我的意见是维护一个作为源代码内的引用文档要比维护一个独立的文档要容易和更实用，因为这个方法更容易保持更新。否则就非常容易变得懒惰从而将对文档的更新推后到无限期（如果一定要给它加个期限，我想是一万年）。相反使用象这样的一个工具，只有一点工作量就是在你正在修改的源代码附近更新一个标记，接着运行工具再一次生成更新过的HTML页面。
一些php文档工具的预览
在对上面了解了之后，我搜索了一下哪些是可用的，并且我发现了如下一些有趣的工具：
phpSearchdoc是enzyme项目的一部分。因为enzyme 是一个巨大的项目，所以需要将其文档化。那里的开发人员已经编写了他们自已的文档系统并且他们非常慷慨地将其作为一个独立的包进行发布。得到的文档首先被写入数据库，然后可以被一些PHP脚本查看，象一个动态的web站点。
从现存的信息中将用于分析的逻辑分离出来的想法相当好，然而phpSearchdoc(版本 1.01)不具有一个真正的分析器，而是从源文件，甚至包括注释中搜索关键字。事实上，对我来说碰巧发生过在我的注释中存在'function'单词，结果分析器愚蠢地认为在这个单词后面的词就是函数的名字。更不幸的是，我不巧在同一行放了一个单引号(')，接着我试图将数据写到数据库中，mysql作出了抱怨（出错了，因为单引号在 mysql中被用于分割字符串）。
而且它的安装及运行相当困难，因为它还是一个alpha测试版。毕竟比起文档系统来说它更象是一个交叉引用生成器，正如我知道的，你不能在函数和方法中加入自已的注释。
phpxref，就象名字所指的比起一个真正 的文档系统来似乎更象是面向交叉引用的生成处理。更进一步说它更适合于正常的过程化编程而不是面向对象编程。
phpautodoc的目标是实现象Javadoc 应用于Java那样用于PHP。它看上去是满足我的文档需求的完美解决。为了试验它我不得不编译了PHP的CGI版本（我通常使用模块版本），因为生成器是用PHP编的。我可能容易地在一个Linux系统下编译和安装静态的执行程序，可以使用这些命令：
rm config.chche
make clean
./configure
make
cp php /usr/local/bin
我决定对它自已的PHP源码进行测试，并且我发现它只有部分可以工作：它只能够生成类的文档（生成整齐的格式），但是不能生成小结。我不知道是否这个只是碰巧发生在我的机器上，但是在试图生成小结时却因为core dump(内核崩溃)而停止（PHP 4.0 pl2，RedHat 6.2环境）。假如在你的机器/usr/local/bin下安装了PHP执行版本，调用它的语法是（为了得到结果我不得不给出php文件和输出目录的全路径）
./phpautodoc -o
phpdoc是一个用来维护在Web站点上的php 文件，并且它非常适合分布式开发方式。文档是从数据库中生成；在安装之后，你可以使用web界面来增加你的类将其文档化。这个的确有意思，但是它是一种低级的从源代码中分离文档的维护方法，这一点就我来说不是非常方便。
通用工具
在经受了试验所有这些工具但却得不到怎么成功的挫折之后，直到Pear Project提出了一种标准的解决方法，我发现了一个与PHP完全无关的可工作的工具在Open Source Projects at Apple站点。项目的名字是 HeaderDoc。就象站点所说的" HeaderDoc是一种从C或C++头文件的注释中生成HTML的引用文档的工具。它是用Perl编写的以便于移植。与JavaDoc 相似，它允许开发者容易地文档化他们的接口，并且将接口信息输出到HTML。"
是的，你看的没错，HeaderDoc只支持C和C++。没有其它的语言，但是它不象JavaDoc，它大部分依赖写在注释中的标记，所以只要做些小改动（我会在后面解释）就可以很好的用在PHP上。这些标记同JavaDoc很象，HeaderDoc标记的一些例子是@class，@function和@var。
文档化一个类
OK，让我们现在进入细节吧。首先让我们看一下一个类如何被文档化。
--------------------------------------------------------------------------------
/*! @class BagItem
@abstract An item in the shopping bag - it is a shopitem with quantity
@discussion A BagItem object may be constructed without previous
instantiation of neither ShopItem nor Product
*/
--------------------------------------------------------------------------------
文档化一个类。可以在左边的帧选择类的方法。
第一件需要注意的事情是用在打开注释上的风格不完全象JavaDoc注释/**(一个斜线和两个星号)，而是换成/*!(一个斜线，一个星号和一个感叹号) 。标记使用也不一样，但是它们以相似的方式工作。例如，第一个标记是@class标记，它用于文档化一个类，这个标记跟着类的名字。下一个标记是@abstract 标记，它
是一个可选的标记，用少量词语来描述一个类的含义，同时@discussion 标记是另一个可选的标记，用于进一步的讨论。当然由你来决定是在@discussion标记中描述所有的事情还是使用@abstract来处理，但是要记住，一般来说，你使用的标记越精确，结果就越好。
文档化函数或方法
成员函数或方法使用@function标记被文档化。
--------------------------------------------------------------------------------
/*! @function getItemingroup
@abstract gets a bagitem of a given group and a given position
@param groupno int - the delivery group ordinal position in the bag
@param pos int - the position of the bagitem within the group
@result Object - the BagItem in a given position of given group
or -1 if it could not be found
*/
--------------------------------------------------------------------------------
文档化一个方法。
@function标记声明了一个函数并且后面跟着函数或成员函数名。然后你可以象前面一样使用 @abstract和@discussion标记。然而还有两个额外的标记。@param标记用于描述函数的参数；第一个词假设为变量的名字，其它的则为任意的文本描述。我建议要声明想要的变量类型，尽管PHP不是一个强类型语言。 @result标记被用于描述返回值。
文档化变量
变量或类变量都使用@var标记来描述。在这个标记中，第一个词被认为是变量的名字，同时其它的则为任意的文本描述。象前面一样，我建议写出所期望的变量类型是好的做法。它也是一个文档化所有类变量的好主意。
文档化一个类变量。
--------------------------------------------------------------------------------
/*! @var idsession string - an unique session identifier */
var $idsession;
--------------------------------------------------------------------------------
最后接触
--------------------------------------------------------------------------------
/*! @header myprojectname
@abstract a virtual store to shop on mars
@discussion The difference [...]
*/
--------------------------------------------------------------------------------
@header标记用来提供一些关于被文档化的项目或类组的一般性信息。@header标记本身跟着项目的名字 ，而且可以用@abstract标记和@discussion标记来补充说明。因为类通常存在于不同的文件中（一个文件一个类，且用类的名字给文件名字是一种好的想法），你可能想知道应该将@header 标记放在什么地方。答案很让人吃惊，哪都可以。我的建议是：如果它比较长就把它放在一个独立的文件中，或如果是一个简短的说明就把它放在最重要的类的前面。
如何修改脚本用于PHP
从Apple得到的初始的HeaderDoc脚本是用于C或C++头文件的，所以要用在PHP中需要对它做一些小改动 。如果你对细节没有兴趣，你可以从这里下 载，并且跳过下面部分。
修改源程序所做的唯一的事情就是在主perl文件中，使脚本可以接受.php和.php3后缀。
--------------------------------------------------------------------------------
$ diff headerDoc2HTML.pl /usr/local/bin/headerdoc2html
195c195
---
> ($rootFileName = $filename) =~ s/.(h|i|php|php3)$//;
--------------------------------------------------------------------------------
运行脚本
在安装完脚本之后，假设你的类放在classes子目录下，并且你想将生成的文档放在docs目录下，你应该执行这个命令：
headerdoc2html -o docs classes/*.php
不幸的是如果存在多个PHP文件，这个脚本有一个坏习惯就是将那些文件分割到不同的目录中去，使得在类的文档中浏览变得很困难。而且因为初始的脚本是为C/C++头文件所写的（头文件中只有类和函数的声明而没有他们的定义），脚本会将函数名下的所有代码输出，直到碰到";"，所以典型的就是代码的第一行。
但是在你好不容易读到现在却感到绝望之前，放松，因为我写了一段简单的脚本来解决这两个问题。
--------------------------------------------------------------------------------
cat classes/*.php | sed 's/ *{/;#{/g' | tr "#" "
" > docs/all.php
headerdoc2html -o docs docs/all.php
rm docs/all.php
--------------------------------------------------------------------------------
如果你想知道为什么我在这里使用tr命令而不是都用sed来做，原因就是用在仍然用在RedHat 6.2上的sed 3.02版本不处理换行符。应该替换成新的版本sed 3.02a。如果你对sed感兴趣，可以看SED FAQ。
祝你的文档化工作好运！