- 本文地址: https://www.laruence.com/2009/04/21/680.html
- 转载请注明出处
最近再总结一些PHP的规范, 想起之前在Y!的时候的API描述自动生成工具, 翻到了phpDocumentor, 用起来感觉还是很方便 , 就安装到使用的过程写下来, 与大家分享
phpDocumentor的安装很简单,
如果通过pear自动安装
在命令行下输入 pear install PhpDocumentor
如果是手动安装
则在http://manual.phpdoc.org/下载最新版本的PhpDocumentor（现在是1.4.2），把内容解压即可.
phpdocumentor的使用也很简单, 分为命令行模式和web模式:
命令行模式
在phpDocumentor所在目录下，输入
php –h
会得到一个详细的参数表，其中几个重要的参数如下：
-f 要进行分析的文件名，多个文件用逗号隔开
-d 要分析的目录，多个目录用逗号分割
-t 生成的文档的存放路径
-o 输出的文档格式，结构为输出格式：转换器名：模板目录。
例如：phpdoc -o HTML:frames:earthli -f test.php -t docs
Web模式
在新的phpdoc中，除了在命令行下生成文档外，还可以在客户端浏览器上操作生成文档，具体方法是先把PhpDocumentor的内容放在 apache目录下使得通过浏览器可以访问到
点击files按钮，选择要处理的php文件或文件夹，还可以通过该指定该界面下的Files to ignore来忽略对某些文件的处理。
然后点击output按钮来选择生成文档的存放路径和格式.
最后点击create，phpdocumentor就会自动开始生成文档了，最下方会显示生成的进度及状态，如果成功，我们就可以通过查看生成的文档了，如果是pdf格式的，名字默认为documentation.pdf。
来看个例子:
代码加上注释:
<?php
/**
* @filename baseTags.php
* @touch date Tue 21 Apr 2009 11:49:12 AM CST
* @package phpDocumentor demo
* @author Laruence
* @license http://www.zend.com/license/3_0.txt PHP License 3.0
* @version 1.0.0
* @copyright (c) 2009, Laruence
*/
/**
* this function is a demo to illustrate how phpdocument tags work
* <code>
* $bool = element(true, "laruence");
* </code>
* @deprecated
* @param bool $bool a flag to decide whether the string should be output
* @param string|int $string sometimes it's a string, sometimes it's a int
* @return bool
*/
function element($bool, $string){
if ($bool){
die("flag off");
}
echo "I love $string";
return true;
}
?>
在命令行模式下输入:
phpdoc -o HTML:frames:default -f baseTags.php -t docs
还有一些其他技巧, 比如, 你可以把phpdoc这个脚本放到/usr/bin目录下, 将phpdoc.ini和phpdocumentor目录放到php设置的include path 下, 就可以把phpdoc当成shell命令来很方便的使用了.
还有, 比如一些文件的描述信息, 完全可以map成vim的一个宏命令, 我自己就把相关的信息都map成了F12,
function MyCopy()
call setline(line("."),"/**")
call append(line(".")+1," * @filename ".expand("%"))
call append(line(".")+2," * @touch date ".strftime("%c"))
call append(line(".")+3," * @author Laruence<huixinchen@baidu.com>")
call append(line(".")+4," * @license http://www.zend.com/license/3_0.txt PHP License 3.0")
call append(line(".")+5," * @version 1.0.0 ")
call append(line(".")+6,"*/")
endf
map <f12> <esc>:call MyCopy()<cr><esc>5j$a
等等.
最后, 生成的API文档见这里: 例子
如果有兴趣, 还可以看看phpdoc的代码, 也是很有意思,呵呵
ps: 相关的tags的说明见phpDocumentor官方网站的说明 tags说明手册
There is definately a great deal to learn about this subject.
I really like all the points you made.
Hi to all, since I am genuinely keen of reading this website’s post to
be updated on a regular basis. It carries nice information.
The “-o” option does not exist.
鸟哥你好，请问我的生成的文件，中文部分成乱码了，有什么解决方法吗？
It’s awesome to go to see this web page and reading the views of all friends about this article, while I am also zealous of getting experience.
My blog post We Buy Houses Hightstown Nj
小试了一下，真的很好用啊。
不错，学习了，可惜我们公司的代码注释的不太规范，无法生成文档了。。。
available that are hand crafted with full lace wigs hide their balding heads lace wigs hair extension salons real human hair extensions lace wig short or long?? there are wigs afro wigs remi human hair hannah montana wig versatile Similar to real lace front wigs clip on hair extensions Here is one of the best sites that hannah montana wigs have the advantage of a put on pieces hair extensions human hair wigs lacefront wig It is a good idea to have your wigs human hair hair wig It is easier to full lace wigs premium lace wigs can cost several hundred dollars Its remi lace wigs near heat sources with this kind of albert einstein costume remi human hair of having a bald head or receding.
sfdsfdsfd
收藏，呵呵。
你刚才说的那个问题, 如果没有文件级注释, 第一个注释会误认为是第一个函数定义的注释, 我想了下, 文件级注释的tag和函数的注释tag应该是不一样的..
之前的phpdoc的代码实在是乱七八糟。
现在的phpDocumentor好多了
你很快~