Phpdocumentor文档规范及文档标签见:http://www.yanue.net/post-93.html.
注释实例:
<?php //----- 文档块 ---------------------------- /** * 以 / ** 开头的注释是一个文档块(DocBlock) */ function a0() {} //----- 文档块描述细节 -------------------- // 文档块包括哪些? /** * 文档块按顺序包括3个部分 * 1. 短描述 * 2. 长描述 * 3. tag段 */ function a1() {} //比如 /** * 短描述 * * 这是一个长描述。 * 继续长描述。 * 如果短描述超过3行,则会只去第一行,作为短描述。 * * 另起一段:因为上面的空行 */ function a2() {} // <p>的例子 /** * 短描述 * * <p>这是一个长描述。 * 继续长描述。 * 用p标签包围的长描述</p> * <p>另起一段</p> * <p>再另起一段</p> */ function a3() {} /** * phpdoc 不支持html的标签,但是可以用下面的几个标签(注意加<>) * * b -- <b> 加粗 </b> * * br -- 换行,<br>可能被某些转换器忽略 <br> * * i -- <i> 斜体 </i> * * kbd -- <kbd> 标示 键盘输入/屏幕输出 </kbd> * * ul -- 没有顺序的列表 * * li -- 列表项 * * ol -- 顺序列表 * * p -- 如果成对使用,则表明一个段,否则只是一个字符串<p> * <p>这是一个段</p> * * pre -- * <pre>原样输出,即使是各种标签<b>加粗</b>,相当于XML的CDATA * 注意输出成HTML后,会有效果 * </pre> * * var -- 变量名 * * samp -- 非php的示例 * * <code> 加粗 </code> * * 不要把这些标签想成是字符串,它们应解析器的不同,而被解析成各种形式 * 如:b标签在DocBook中是<emphasis>,p标签在PDF中是4个空格 * 这些都在模板的options.ini文件中定义 * * 要显示带前后尖括号的b标签,可以用《《XXX》》(小写尖括号), 如<<b>> * * 要用@标签,如果行的开头,则用@,其他地方不需要加反斜杠 * 如: * * <code> * @return abc * 这是一个标签 @name * </code> */ function a4() {} /** * 简单的列表(不允许嵌套,因为它不再简单) * * 这是一个简单的列表(以-、+、#、o) * - item 1 * - item 2, this one * is multi-line * 这是一个简单的列表(以-、+、#、o) * + item 1 * + item 2 * 这是一个简单的列表(以-、+、#、o) * # item 1 * # item 2 * 这是一个简单的列表(以-、+、#、o) * o item 1 * o item 2 * 列表结束。下面是顺序列表(以数字开头) * 1 ordered item 1 * 2 ordered item 2 * 列表结束。下面是还是顺序列表(以数字开头,并且有个点) * 1. ordered item 1 * 2. ordered item 2 */ function a5() {} /** * 有嵌套的列表 * * 使用ul li ol等标签创建复杂的嵌套列表 * <ul> * <li>outer item 1</li> * <li>outer item 2, this one * is multi-line</li> * <li>item 3 is a nested inner list * <ul> * <li>inner item 1</li> * <li>inner item 2</li> * </ul> * <li>outer item 4</li> * </ul> */ function a6() {} /** * 在todo标签中的列表 * @todo My Simple TODO List * - item 1 * - item 2 * - item 3 * - item 3 * @todo My Complex TODO List * <ol> * <li>item 1.0</li> * <li>item 2.0</li> * <li>item 3.0</li> * <li> * <ol> * <li>item 3.1</li> * <li>item 3.2</li> * </ol> * <li> * <li>item 4.0</li> * </ol> */ function a7() {} //----- Tags ------------------------------------ // Tags:以@开头的标示 // 下面是常用的Tag /** * 简单的描述 * * 你可以任意扩展描述,成千上万行都可以 * * 用 {@link ellement} 指向一个 element * 比如:指向a1: {@link a1} * * 用 {@link url} 指向一个站点 * 比如:{@link http://www.sina.com.cn 新浪网} * * 用 {@source} 显示源代码. * 比如:显示函数的代码: * {@source } * * 可用Tag列表: * type 是PHP类型:integer, array, mixed, string等 * * - @abstract * - @access public or private * - @author 作者 <author@email> * - @copyright 版权 * - @deprecated 废弃 * - @deprec deprecated的简写 * - @example 指向例子 * - @exception 兼容javadoc * - @global type $globalvarname * - @global type 函数中的全局变量描述 * - @ignore * - @internal 给高级程序员看的内部细节描述 * - @param type [$varname] 描述 * - @return type 描述 * - @link URL * - @name procpagealias [不懂] * - @name $globalvaralias * - @magic 兼容phpdoc.de * - @package 包名 * - @see 指向其他元素的名字,如函数名,类方法等 * - @since 一个版本号或日期 * - @static * - @staticvar type 函数中的静态变量的描述 * - @subpackage 子包 * - @throws 兼容Javadoc * - @todo 待办列表,兼容phpdoc.de * - @var type 类变量的类型 * - @version 版本 */ function if_there_is_an_inline_source_tag_this_must_be_a_function() { // ... } //----- 可以文档的源代码元素 ------------------------------------ //-- 包 /* * Phpdoc划分包的逻辑: * 函数、常量、全局变量属于包 * 方法、类变量属于类 * 包可以包含多个类 * * 一个文件中不要包含多个包 */ //--- 程序文件级 -------------------- /* * 文件的第一个块就是 文件级的文档块(page-level Docblock) * 或者包含@package标签 * 它可以有这些元素: * 标准标签 * @package * @subpackage * */ //--- Include/Require 语句 ---------- /* * 它可以有这些元素: * 标准标签 */ //--- define 语句 ------------------- /* * 它可以有这些元素: * 标准标签 * @name */ //--- function 声明 ------------------- /* * 它可以有这些元素: * 标准标签 * @global * @param * @return * @staticvar * inline {@source} */ //--- 全局变量 ------------------------ /* * 它可以有这些元素: * 标准标签 * @name */ //--- class 声明 ------------------- /* * 它可以有这些元素: * 标准标签 * @package * @subpackage * @static */ //--- class 变量 ------------------- /* * 它可以有这些元素: * 标准标签 * @var */ //--- class 变量 ------------------- /* * 它可以有这些元素: * 标准标签 * @global * @param * @return * @static * @staticvar * inline {@source} */ /* * 标准文档标签 * 常用的: * @author * @copyright * @version * @since * @link * @see * 其他: * @tutorial * @example * @access * @deprecated * @ignore * @internal * inline {@internal}} * inline {@inheritdoc} * inline {@link} */ /* * 文档标签的继承关系 * * Class子类可以继承父类的文档,几个简单的规则: * * @author, @version, @copyright 自动继承,除非显示指明 * @package and @subpackage 也会继承,但是建议显示申明,以避免名字冲突 * 如果没有简单描述,则会继承 * 如果没有长简单描述,则会继承 * 如果有长描述,想继承父类的描述,则使用inline标签 {@inheritdoc} */ //----- 命令行参数说明 ------------------------------------ // phpdoc -h 查看帮助, 参数如下: // /* -c --config 载入配置文件,如:-c defualt ;载入default.ini文件 * -cp --converterparams 动态扩展转换器的参数,多个值用逗号分割 * -ct --customtags 自定义tag,多个值用逗号分割;如:-ct mgtag,yourtag => @mytag @yourtag * -d --directory 指定要解析的目录 * -dc --defaultcategoryname 指定默认分类名,默认值为:defaul * -dh --hidden 相当于-dh on,让phpdoc解析以.开头的隐藏文件和目录 * -dn --defaultpackagename 指定默认包名,默认是:default * -ed --examplesdir 例子文件寻找路径,如:-ed /full/path/to/example * -f --filename 要解析的源文件名,用,分割,可以使用 * ? * -i --ignore 不解析的文件名或目录,用,分割,可以使用 * ? ; * - -i 忽略 /path/to/here/tests/* 和 /path/tests/* * - -i *.inc 忽略所有的 .inc 文件 * * - -i *path/to/* 忽略 /path/path/to/my/* 和 /path/to/* * - -i *test* 忽略 /path/tests/* 和 /path/here/my_test.php * -is --ignoresymlinks 忽略任何链接文件,这个只在Linux/Unix下有效,因为Win下没有链接文件 * -it --ignore-tags 忽略某些tag;通常用于创建不同版本的文档;如给普通用户的文档,就不需要@todo标签 * 忽略inline标签,加上大括号,如--ignore-tags {@internal} * 参数是完整名字,如-it @todo, -it todo 是错误的写法 * -j --javadocdesc 使用javadoc兼容标签 * -o --output 指定要使用的转换器和模板;默认可选: * HTML:frames:* - 输出带框架的HTML页面 * HTML:frames:default - 类Javadoc模板,没有太多格式 * HTML:frames:earthli - Marco von Ballmoos写的模板,非常漂亮 * HTML:frames:l0l33t - 非常漂亮的模板 * HTML:frames:phpdoc.de - 类phpdoc.de's PHPDoc * HTML:frames:phphtmllib - 非常好的用户发行模板 * 以上模板都有javascript增强版本:HTML:frames:DOM/name 其中name表示 default, l0l33t, phpdoc.de, 等等 * HTML:frames:phpedit - 基于PHPEdit帮助生成器 * * HTML:Smarty:* - 输出不带框架的HTML * HTML:Smarty:default - 用css控制页面布局的模板 * HTML:Smarty:HandS - Layout is based on PHP, but more refined, with logo image * HTML:Smarty:PHP - Layout is identical to the PHP website * * CHM:default:* - 输出成CHM格式,需要用Windows的Help软件编译 * CHM:default:default - 基于HTML:frames:l0l33t * * PDF:default:* - 输出成PDF文档 * PDF:default:default - 标准格式 * * XML:DocBook:* - 输出成XML--DocBook格式 * XML:DocBook/peardoc2:default - pear.php.net(第2版) * * -p --pear Parse a PEAR-style repository (package is directory, _members are @access private) on/off default off * -po --packageoutput output documentation only for selected packages. Use a comma-delimited list * -pp --parseprivate 开启;默认不显示@access private的文档 * -q --quiet 关闭多余信息;用法:-q on --不显示 -q off --显示,默认值 * -ric --readmeinstallchangelog Specify custom filenames to parse like README, INSTALL or CHANGELOG files * -s --sourcecode generate highlighted sourcecode for every parsed file (PHP 4.3.0+ only) on/off default off * -t --target 要输出的路径 * -ti --title 文档的标题 * -tb --templatebase 指定自己的模板目录 * -ue --undocumentedelements 为没有文档的元素 产生警告; 用法:-ue on -ue off (默认值) */ /* * phpdoc -t /path/to/output -d path/to/directory1,/another/path,/third/path * -f /path/to/anotherfile.php -i *test.php,tests/ -pp on -ti My Title -o HTML:frames:phpedit * * phpdoc -c myconfig */ ?>
来自: http://sofire.iteye.com/blog/120007
转载请注明:半叶寒羽
» phpdoc文档注释实例