技术头条 - 一个快速在微博传播文章的方式     搜索本站
您现在的位置首页 --> PHP --> phpDocumentor

phpDocumentor

浏览:2511次  出处信息

最近再总结一些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说明手册

建议继续学习:

  1. 规范自己的JavaScript书写    (阅读:5964)
  2. PHP编码规范    (阅读:4341)
  3. 数据库开发规范    (阅读:3382)
  4. 分清“语言/规范”以及“平台/实现”,以及跨平台.NET开发    (阅读:3174)
  5. Android 4.0设计规范 优先导读 十大改变 (附全文翻译pdf)    (阅读:2730)
  6. 编码风格不是编码规范    (阅读:2602)
  7. 良好的书写规范提高PHP代码执行效率    (阅读:2565)
  8. 网站css样式命名规范和应用原则    (阅读:2450)
  9. 前端编码规范(1)—— 一般规范    (阅读:2048)
  10. Flash应用安全规范    (阅读:1837)
QQ技术交流群:445447336,欢迎加入!
扫一扫订阅我的微信号:IT技术博客大学习
© 2009 - 2024 by blogread.cn 微博:@IT技术博客大学习

京ICP备15002552号-1