第七星尘

使用phpdoc来生成api文档

phpDocumentor是一个非常强大的文档自动生成工具,利用它可以帮助我们编写规范的注释,生成易于理解,结构清晰的文档,
对我们的代码升级,维护,移交等都有非常大的帮助。
网上关于phpdoc的文档的介绍虽然不少,但是有点麻烦:
1、网上通常介绍的内容太多,不容易被新手看懂。个人觉得,教程应该本着简单易懂,在能解决问题的前提下,能有多简单就多简单。
更多的内容,应该以附录的形式,或者留下其他更详细的资料链接供读者去阅读(而不是把一大块都复制进自己的文章)
2、phpdoc的安装稍微麻烦。他们没有介绍一种简单易上手的方法给读者
3、phpdoc的默认编码是ISO-8859-1,此时生成的HTML文档会中文乱码。尽管说网上有提供了解决方案——但是,为什么不直接提供一个可支持中文的版本给读者呢?
基于以上几点,我想写篇博文,跟大家分享一个使用phpdoc的简单方法(windows环境下)
在使用phpdoc之前,你首先需要了解代码注释的语法规则(如果你已经懂,请忽略)。
可参考维基本科http://zh.wikipedia.org/wiki/PHPDoc 中关于注释格式的描述部分。
接着,可下载这个经过优化的phpdoc版本:
http://120.25.163.70/blog/wp-content/uploads/2013/04/phpdoc.zip
下载后解压,比如说解压到”D:/phpdoc”路径下。
用文本编辑器打开phpdoc.bat(注意,不是双击运行),第16行:
SET phpCli=D:Program Filesphp5.3.11php.exe
将这里的PHP.exe的路径改为你电脑的php环境执行文件所在的路径。(如果你是PHPer,我相信你在本机有安装了php环境吧。)
然后,打开命令提示符。(开始-运行-cmd),在命令行中,进入phpdoc所在的目录,(比如说,输入“cd D:/phpdoc”)。
进入目录后,输入下面的命令,便可快速生成HTML文档:
phpdoc -d D:websiteApi -t D:websiteApidoc -dn shilianwang -dc shilianwang -ti 事联网文档 -o HTML:Smarty:PHP
上述命令中,D:websiteApi是源php文件所在目录。D:websiteApidoc 是生成的文档存放目录。
shilianwang是子目录,包、标题。HTML:Smarty:PHP 表示使用HTML模块生成
上面的命令,如果你想详细了解,可在命令行输入phpdoc -h ,了解更多。
最后,附上三种效果图:
 
 注释的样式:

该注释生成的效果图:

 如无特殊说明,本站皆为原创。转载请注明来自第七星尘的技术博客《使用phpdoc来生成api文档》

评论

  1. 李惟 #1

    The "-o" option does not exist.

    回复
    2014-01-5
  2. Saber #2

    学习了

    回复
    2013-12-8