phpdoc文档格式

Phpdocumentor文档的阅读笔记

把 PhpDocumentor/phpDocumentor/Converter.inc 的4209行的
$this->class_data->append('consts',array_merge(
改成了
$this->page_data->append('consts',array_merge(
不知道对不对

<?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
 */

?>