注册 登录  
 加关注
   显示下一条  |  关闭
温馨提示!由于新浪微博认证机制调整,您的新浪微博帐号绑定已过期,请重新绑定!立即重新绑定新浪微博》  |  关闭

天边云E家 shaoruisky

IT博文共享,知识的海洋

 
 
 

日志

 
 

PhpDocumentor 开发文档制作  

2014-02-07 17:15:39|  分类: php |  标签: |举报 |字号 订阅

  下载LOFTER 我的照片书  |

写文件是一个程序设计师最最痛苦的事情之一,尤其是写了一堆程序后有人要你把 Function ,Class 等等等等,写成一份文件。

这事情不管你是写 c/c++ , perl , ruby , php 都不例外。

phpDocumentor 是我们的救星! 只要在写程序的时候,乖乖的写一点注解,写一点范例,多一点说明,注意一下格式,等到程序完工后,只要一个指令,就可以立刻把全部程序的说明文件产生出 来,而且还有多种样式可以选择,甚至可以作成 PDF , CHM 喔...

好了,屁话不多说,先来说说怎么装上这好用的东西吧...

phpDocumentor 本身已经是 pear 的成员之一,所以安装的时候只要用 pear 来安装即可(以下范例为在 Windows 下进行,以后再补上 LInux 下的)

--如果你已经有装 php 跟 pear 请跳过--

首先假设我把我的的 php 安装路径在 d:\php\

也就是说我从 www.php.net 下载了最新的 php win32 安装档案,解开后放在 d:\php\

那么这个目录下面应该有 d:\php\PEAR这个目录,但是当你进去看的时候,你会发现好像没有 PEAR 相关程序库阿...

没错,这个时候你还没有安装 PEAR 请先用 go-pear.php 安装基本 pear 环境。

那么在 d:\php 目录下有一个档案,叫做 go-pear.bat 请开一个 cmd 视窗去执行他,中间会有一些问题,基本上都照预设值去跑就可以了...

跑玩后,你的 pear 应该会被安装在 d:\php\PEAR\pear 下面,而帮助你安装其他 pear 套件的 pear.bat 则在 d:\php\PEAR下面

--安使安装 phpDocumentor --

安装 phpDocumentor 的过程也很简单,只要利用 pear.bat 即可!

使用指令如下

d:\php\PEAR\pear.bat install -o PhpDocumentor

当中有多下一个 -o 的参数,意思是要 pear 把相依的套件也一起下载安装。

安装完成后 d:\php\PEAR 下面应该会多一个 phpdoc.bat 的批次档,我们就可以用这个批次档来产生我们的文件。

-- 使用 phpdoc.bat 产生文件 --

产生文件的方式我通常只有用下面一行指令解决:

d:\php\PEAR\phpdoc.bat -o HTML:Smarty:PHP -d d:\myProject\php_source\ -t d:\myProject\docs

这样子的意思是说,采用 HTML:Smarty:PHP 的样板格式,然后原始码目录在 d:\myProject\php_source\ ,接着把产生的文件放在 d:\myProject\docs 底下。

当中若是你只要对一个档案作文件的话,可以把 -d 改成 -f 然后后面接的着就是指定的档名。

样板的格式基本上有 HTML, XML, PDF, CHM 四大类别,通常我用的都是 HTML:Smarty:PHP 这个,因为他比较好看!

另外还有就是 CHM:default:default 这个.用来产生 chm 的,不过他产生出来的是 .hhp 档案,也就是还没有经过 HTML helper 编译过的档案,所以要另外安装 HTML Helper 来编译 hhp 档案就可以产生你要的档案。

-- 最后来说一下怎么写注解 --

phpDocumentor 的注解有一定的规格,但是都跟我们原来写注解的方式很像,只是要注意一下东西而已。

简单的来看个范例好了

<?php

/**

* 这里是这个物件的说明

* 可以多行喔!~

*

*/

class MyClass {

   /**

   * 这里是变量的说明

   *

   * @var int

   */

   var $a ;

   /**

   * 这里是变量的说明.

   *

   * @var string 这里也可以放说明

   */

   var $b ;

   

   /**

   * 这是针对函式的说明

   * 也是一样可以多行

   * 若是简单的范例也可以放这里

   *

   * @param int $a 可以放入传入的型态

   * @return array 可以说明回传的型态

   */

   function first ( $a ) {

      return array();

   }

}

?>

基本上都是在

/**

*

*/

中间写注解,别忘了每行前面要有个 * 喔!

注解比较常用到参数的应该是

@author 程序作者名称,联络方式

@const 常数

@deprecate 不建议使用的 API

@global 全域变量

@param 函数的参数

@return 回传值

@see 可参考函数

@since 开始时间

@static 静态变量

@var 物件成员变量

@todo 计划中要进行的项目

  评论这张
 
阅读(104)| 评论(0)
推荐 转载

历史上的今天

在LOFTER的更多文章

评论

<#--最新日志,群博日志--> <#--推荐日志--> <#--引用记录--> <#--博主推荐--> <#--随机阅读--> <#--首页推荐--> <#--历史上的今天--> <#--被推荐日志--> <#--上一篇,下一篇--> <#-- 热度 --> <#-- 网易新闻广告 --> <#--右边模块结构--> <#--评论模块结构--> <#--引用模块结构--> <#--博主发起的投票-->
 
 
 
 
 
 
 
 
 
 
 
 
 
 

页脚

网易公司版权所有 ©1997-2017