本文共 5066 字，大约阅读时间需要 16 分钟。

1.    为什么要写注释文档？ 任何软件项目想要成功的关键之一是有好的文档，写出好的文档甚至要比写出好的代码更为重要。作为阅读代码时的第一印象，注释能够让开发人员深入你的代码。phpDocument就是为了跟容易生成文档而出现的，她甚至可以为想同的代码生成不同的文档集。 2.    使用phpDocumentor生成两种不同的文档 事实上，我们常常需要生成两种文档提供给不同的用户，例如我们可以生成“使用手册”给最终用户，生成“编程手册”给程序员。更深一步，我们可以使用@access标记来标明程序级的元素的访问属性，也可以使用@internal标记来标明文档的访问权限。 3.    phpDocumentor是什么？可以用来做什么？ phpDocumentor是一个用PHP实现的，能够直接从PHP代码或者外部文档生成完整文档的工具。事实上，php代码本身是清楚易懂得，甚至可以直接作为自己的说明文档。phpDocumentor通过解析PHP代码的逻辑结构（例如文件，类，函数，常量，全局变量，类成员/方法等），重新整理之后生成普通的可读说明文档。在1.3.0版之后，PHP5中新加入的代码元素（如类常量，接口等）也可以解析了。输出的文档有多种格式（HTML，PDF，CHM），因此通过web浏览器浏览、打印及整合至IDE。 phpDocumentor通过读取代码中一种特殊的注释(DocBlock)来生成说明文档。作为项目开发者，将对他人有帮助意义的信息写入DocBlock。 尽管添加简洁信息在代码里是必要的，但是不能代替真正那些不能写在源代码中的那些“冗长”信息，比如用户使用手册和说明文档。 4.    安装phpDocumentor 有两种方法安装phpDocument，一种是通过pear安装，另外一种是通过源码安装。 pear安装： $ pear install PhpDocumentor 源码安装： 下载代码：http://sourceforge.net/projects/phpdocu/files/ 安装有PHP的环境，就可以执行源码包的phpdoc的命令行程序了 5.    一个简单的使用示例 $ phpdoc -o HTML:frames:earthli -f sample1.php -t docs -o选项表示输出文件格式，-f表示要分析的代码文件，-t表示输出的目录 查看帮助使用：phpdoc –h 6.    phpDocument基础 （1）    基本的docblock

/****/

 

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

/*** Short desc** Long description first sentence starts here* and continues on this line for a while* finally concluding here at the end of* this paragraph** The blank line above denotes a paragraph break*/

 

（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模板以’/**#@+**/’开头，以’/**#@-*/’结尾

class Bob{   // beginning of docblock template area   /**#@+   * @access private   * @var string   */   var $_var1 = 'hello';   var $_var2 = 'my';   var $_var3 = 'name';   /**    * Two words    */    var $_var8 = 'like strings';    /**#@-*/    var $publicvar = 'Lookee me!';}

 

会解析成：

class Bob{    // beginning of docblock template area    /**     * @access private     * @var string     */    var $_var1 = 'hello';    /**     * @access private     * @var string     */    var $_var2 = 'my';    /**     * @access private     * @var string     */var $_var3 = 'name';    /**     * Two words     * @access private     * @var string     */    var $_var8 = 'like strings';    var $publicvar = 'Lookee me!';}

 

（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}

转载地址：http://axsni.baihongyu.com/