如何文档化你的PHP类(二)
Jun 21, 2016 am 08:58 AM
abstract
nbsp
php
quot
如何文档化你的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|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
本站声明
本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系admin@php.cn

热门文章
仓库:如何复兴队友
3 周前
By 尊渡假赌尊渡假赌尊渡假赌
R.E.P.O.能量晶体解释及其做什么(黄色晶体)
1 周前
By 尊渡假赌尊渡假赌尊渡假赌
Hello Kitty Island冒险:如何获得巨型种子
3 周前
By 尊渡假赌尊渡假赌尊渡假赌
击败分裂小说需要多长时间?
3 周前
By DDD
公众号网页更新缓存难题:如何避免版本更新后旧缓存影响用户体验?
3 周前
By 王林

热门文章
仓库:如何复兴队友
3 周前
By 尊渡假赌尊渡假赌尊渡假赌
R.E.P.O.能量晶体解释及其做什么(黄色晶体)
1 周前
By 尊渡假赌尊渡假赌尊渡假赌
Hello Kitty Island冒险:如何获得巨型种子
3 周前
By 尊渡假赌尊渡假赌尊渡假赌
击败分裂小说需要多长时间?
3 周前
By DDD
公众号网页更新缓存难题:如何避免版本更新后旧缓存影响用户体验?
3 周前
By 王林

热门文章标签

记事本++7.3.1
好用且免费的代码编辑器

SublimeText3汉化版
中文版,非常好用

禅工作室 13.0.1
功能强大的PHP集成开发环境

Dreamweaver CS6
视觉化网页开发工具

SublimeText3 Mac版
神级代码编辑软件(SublimeText3)

适用于 Ubuntu 和 Debian 的 PHP 8.4 安装和升级指南

如何设置 Visual Studio Code (VS Code) 进行 PHP 开发
