当前位置:首页> PHP教程> PHP精通
关键字
文章内容
如何文档化你的PHP类(二)
 
 
修改时间:[2011/09/04 21:37]    阅读次数:[400]    发表者:[起缘]
 
如何文档化你的PHP类()

[br]

作者stefano Locati 翻译limodou 



文档化函数或方法 

  成员函数或方法使用
@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)$//; 

--- 

>     ($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。 



  祝你的文档化工作好运
 



翻译后话
 

  由于这篇文章是在Linux环境下使用的
所以在windows下的使用可能会有问题。我会试一试能想办法就想了实在想不出来也没有办法了。 



原作者
limodou 

来源
PHPX &nbs
 
 
 
 

威尼斯人唯一官网