如何文档化你的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++头文件所写的（头文件中只有类和函数的声明而没有他们的定义），脚本会将函数名下的所有代码输出，直到碰到";"，所以典型的就是代码r

本站关键词：

|东莞主机托管|东莞画册设计|东莞包装设计|东莞产品目录设计|东莞产品推广策划|东莞VI设计|东莞企业形像设计|东莞产品包装设计|东莞海报设计|东莞PHP主机|东莞动态空间|东莞动态网页||东莞主机托管|东莞画册设计|东莞包装设计|东莞产品目录设计|东莞产品推广策划|东莞VI设计|东莞企业形像设计|东莞产品包装设计|东莞海报设计|东莞PHP主机|东莞动态空间|东莞动态网页||东莞主机托管|东莞画册设计|东莞包装设计|东莞产品目录设计|东莞产品推广策划|东莞VI设计|东莞企业形像设计|东莞产品包装设计|东莞海报设计|东莞PHP主机|东莞动态空间|东莞动态网页||东莞主机托管|东莞画册设计|东莞包装设计|东莞产品目录设计|东莞产品推广策划|东莞VI设计|东莞企业形像设计|东莞产品包装设计|东莞海报设计|东莞PHP主机|东莞动态空间|东莞动态网页||东莞主机托管|东莞画册设计|东莞包装设计|东莞产品目录设计|东莞产品推广策划|东莞VI设计|东莞企业形像设计|东莞产品包装设计|东莞海报设计|东莞PHP主机|东莞动态空间|东莞动态网页||东莞主机托管|东莞画册设计|东莞包装设计|东莞产品目录设计|东莞产品推广策划|东莞VI设计|东莞企业形像设计|东莞产品包装设计|东莞海报设计|东莞PHP主机|东莞动态空间|东莞动态网页||东莞主机托管|东莞画册设计|东莞包装设计|东莞产品目录设计|东莞产品推广策划|东莞VI设计|东莞企业形像设计|东莞产品包装设计|东莞海报设计|东莞PHP主机|东莞动态空间|东莞动态网页||东莞主机托管|东莞画册设计|东莞包装设计|东莞产品目录设计|东莞产品推广策划|东莞VI设计|东莞企业形像设计|东莞产品包装设计|东莞海报设计|东莞PHP主机|东莞动态空间|东莞动态网页||东莞主机托管|东莞画册设计|东莞包装设计|东莞产品目录设计|东莞产品推广策划|东莞VI设计|东莞企业形像设计|东莞产品包装设计|东莞海报设计|东莞PHP主机|东莞动态空间|东莞动态网页||东莞主机托管|东莞画册设计|东莞包装设计|东莞产品目录设计|东莞产品推广策划|东莞VI设计|东莞企业形像设计|东莞产品包装设计|东莞海报设计|东莞PHP主机|东莞动态空间|东莞动态网页||东莞主机托管|东莞画册设计|东莞包装设计|东莞产品目录设计|东莞产品推广策划|东莞VI设计|东莞企业形像设计|东莞产品包装设计|东莞海报设计|东莞PHP主机|东莞动态空间|东莞动态网页||东莞主机托管|东莞画册设计|东莞包装设计|东莞产品目录设计|东莞产品推广策划|东莞VI设计|东莞企业形像设计|东莞产品包装设计|东莞海报设计|东莞PHP主机|东莞动态空间|东莞动态网页||东莞主机托管|东莞画册设计|东莞包装设计|东莞产品目录设计|东莞产品推广策划|东莞VI设计|东莞企业形像设计|东莞产品包装设计|东莞海报设计|东莞PHP主机|东莞动态空间|东莞动态网页||东莞主机托管|东莞画册设计|东莞包装设计|东莞产品目录设计|东莞产品推广策划|东莞VI设计|东莞企业形像设计|东莞产品包装设计|东莞海报设计|东莞PHP主机|东莞动态空间|东莞动态网页|