phpdoc文档格式
Phpdocumentor文档的阅读笔记
把 PhpDocumentor/phpDocumentor/Converter.inc 的4209行的
$this->class_data->append('consts',array_merge(
改成了
$this->page_data->append('consts',array_merge(
不知道对不对
把 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
*/
?>