phpDocumentor基础

1. 安装

Pear install phpDocumentor

2. 使用

例子：phpdoc -d "classes" -t "/home/feng/cbti/phpdoc1" -o "CHM:default:default"

<? 命令解释 ?> 

-f

要进行分析的文件名，多个文件用逗号分割

-d

要分析的目录，多个目录用逗号分割

-t

生成的文档的存放路径

-o

输出的文档格式，结构为输出格式:转换器名:模版目录，例如：HTML:frames:phpedit

查看帮助使用：phpdoc –h

3. phpDocument基础

（1）    基本的docblock

Php代码  

1. /** 
2. * 
3. */  

 

（2）docblock的基本组成：短描述，长描述，标签

Java代码  

1. /** 
2. * Short desc 
3. * 
4. * Long description first sentence starts here 
5. * and continues on this line for a while 
6. * finally concluding here at the end of 
7. * this paragraph 
8. * 
9. * The blank line above denotes a paragraph break 
10. */  

 

（3）docblock的描述标记
<b> -- 强调/黑体
<code> -- 用于围绕php代码，可以显示语法高亮
<br> -- 换行标识，但有可能被一些文档转换器忽略
<i> -- 斜体，用于表示重要的内容
<kbd> -- 代表键盘输入/屏幕显示
<li> -- 列表元素
<ol> -- 顺序列表
<p> -- 段落标记
<pre> -- 换行和空格保留标记（把所有标记认为是纯文本）
<samp> -- 代表例子（非php）
<ul> -- 无序列表
<var> -- 代表变量名
特殊用法：
a)    在极少的情况下，<b>用<<b>>来表示
b)    如果需要在docblock中使用’@’符号，需要加上转义符，即用’\@’表示
c)    如果需要在docblock中使用’*/’符号，需要使用’{@*}’
（4）    docblock模板
从1.2.0版开始，phpDocumentor支持docblock模板功能，模板可以减少大量的重复注释写入，比如，如果很多类成员都是私有成员，你就可以使用docblock模板来标明这些变量都是私有的：
docblock模板以’/**#@+**/’开头，以’/**#@-*/’结尾

Php代码  

1. class Bob  
2. {  
3.    // beginning of docblock template area  
4.    /**#@+ 
5.    * @access private 
6.    * @var string 
7.    */  
8.    var $_var1 = 'hello';  
9.    var $_var2 = 'my';  
10.    var $_var3 = 'name';  
11.    /** 
12.     * Two words 
13.     */  
14.     var $_var8 = 'like strings';  
15.     /**#@-*/  
16.     var $publicvar = 'Lookee me!';  
17. }  

 

会解析成：

Php代码  

1. class Bob  
2. {  
3.     // beginning of docblock template area  
4.     /** 
5.      * @access private 
6.      * @var string 
7.      */  
8.     var $_var1 = 'hello';  
9.     /** 
10.      * @access private 
11.      * @var string 
12.      */  
13.     var $_var2 = 'my';  
14.     /** 
15.      * @access private 
16.      * @var string 
17.      */  
18. var $_var3 = 'name';  
19.     /** 
20.      * Two words 
21.      * @access private 
22.      * @var string 
23.      */  
24.     var $_var8 = 'like strings';  
25.     var $publicvar = 'Lookee me!';  
26. }  

 

（5）标签
标签就是以’@’开头的一个标记，用于告诉phpDocumentor如何表示信息以及修改文档的展示方式。
* @abstract
* @access          共有或者私有
* @author          作者姓名 <作者email>
* @copyright        名称 日期
* @deprecated      描述
* @deprec       描述的别名
* @example        /path/to/example
* @exception       与Javadoc兼容
* @global          类型 $globalvarname 
   or
* @global           函数中使用的全局变量描述
* @ignore
* @internal         内部信息或者高级程序员使用
* @param           类型 [$varname] 描述
* @return           类型 描述
* @link             URL
* @name           页面别名
   or
* @name           全局别名
* @magic           兼容phpdoc.de
* @package         包名称
* @see          名称或其他能记录在文档中的内容,
*                  在文档中生成一个指向内容的链接
* @since           版本或者日期
* @static
* @staticvar        函数中使用的静态变量的描述
* @subpackage     项目中分组后的子包
* @throws       兼容Javadoc
* @todo         兼容phpdoc.de
* @var            类型，类成员的数据类型
* @version        版本

7.    生成PHP项目文档
（1）    准备工作
先使用phpDocumentor测试一下你的项目吧
（3）使用命令行工具（linux）
-c, --config
用于加载配置文件
-cp, --converterparams
用于传递扩展转换器的动态参数，选项以逗号分隔
-ct, --customtags
自定义标签选项，选项以逗号分隔
-dh, --hidden
使用此选项用于屏蔽分析以.开头的文件
-dc, --defaultcategoryname
用于设置任何未分类的文件的默认分类
-dn, --defaultpackagename
用于设置任何未定义包名称的默认包名称
-d, --directory
这个选项或者-f选项必须要制定，如果使用-d，则会递归的分析指定的目录下以.php结尾的文件
-ed, --examplesdir
指定实例文件夹
-f, --filename
这个选项或者-d必须指定一个，如果使用-f，会分析单个文件
-i, --ignore
设置需要忽略的文件或者目录
-is, --ignoresymlinks
设定忽略符号链接
-it, --ignore-tags
设定忽略标签
-j, --javadocdesc
设定解析时兼容javadoc格式
-o, --output
设置输出文件的格式
      HTML:frames:* - 包含iframe的HTML格式
      HTML:frames:default – Javadoc风格的文档模板，很少有格式
      HTML:frames:earthli – 漂亮的模板（作者：Marco von Ballmoos）
      HTML:frames:l0l33t – 流行模板
      HTML:frames:phpdoc.de – 类似于phpdoc.de的PHPDoc输出
      HTML:frames:phphtmllib – 非常棒的用户贡献模板
      HTML:frames:phpedit – 基于PHPEdit Help Generator的文档
      HTML:Smarty:* - 不使用iframe的HTML格式
      HTML:Smarty:default – 使用css控制的黑体模板
      HTML:Smarty:HandS – 基于PHP的格式，但是经过优化，带有logo图片
      HTML:Smarty:PHP – 风格接近PHP官网
      CHM:default:* - 输出CHM帮助文档
      CHM:default:default – windows帮助文档，基于HTML:frames:l0l33t
      PDF:default:* - PDF格式
      PDF:default:default – 标准纯文本PDF格式
      XML:DocBook:* - 以DocBook格式输出的XML
      XML:DocBook/peardoc2:default – 可以被编译成peardoc的文档
-pp, --parseprivate
默认情况下，phpDocumentor不会把标记为@access private纳入文档，使用此选项可以将其纳入
-po, --packageoutput
使用此选项会将输出文档中以@package分组的标记（逗号分隔）删除
-p, --pear
使用此选项可以解析pear风格的文档
-q, --quiet
此选项将压缩命令行的输出
-s, --sourcecode
使用此选项会为每一个被解析的文件生成高亮代码，谨慎使用
-t, --target
目标路径，设定输出文档的目录
-tb, --templatebase
接受一个路径作为它的参数，设置文档模板的路径，不指定情况下为<phpDocumentor install directory>/phpDocumentor，phpDocument会在此路径的子文件夹下搜索可用的模板
-ti, --title
生成的文档的标题
-ue, --undocumentedelements
这个选项用于设置在遇到没有docblock标记的class或者method时，是否输出warning信息
8.    代码中的标签
define声明：
@name
函数声明：
@global
@param
@return
@staticvar
inline{@source}
全局变量：
@name
类元素：
@package
@subpackage
@static
继承标签：
在子类的docblock前使用关键字inherite指定从父类继承docblock，可以覆盖
类变量：
@var
类方法
@global
@param
@return
@static
@staticvar
inline{@source}