PhpDocumentor支持的常用标签

来源：互联网发布：清明梦软件编辑：程序博客网时间：2024/06/05 10:43

??附表1: PhpDocumentor支持的常用标签：

　　@abstract 申明变量/类/方法

　　@access指明这个变量、类、函数/方法的存取权限

　　@author 函数作者的名字和邮箱地址

　　@category 组织packages

　　@copyright指明版权信息

　　@const指明常量

　　@deprecate指明不推荐或者是废弃的信息

　　@example 示例

　　@exclude指明当前的注释将不进行分析，不出现在文挡中

　　@final指明这是一个最终的类、方法、属性，禁止派生、修改。

　　@global指明在此函数中引用的全局变量

　　@include指明包含的文件的信息

　　@link定义在线连接

　　@module定义归属的模块信息

　　@modulegroup定义归属的模块组

　　@package定义归属的包的信息

　　@param定义函数或者方法的参数信息

　　@return定义函数或者方法的返回信息

　　@see定义需要参考的函数、变量，并加入相应的超级连接。

　　@since 指明该api函数或者方法是从哪个版本开始引入的

　　@static 指明变量、类、函数是静态的。

　　@throws指明此函数可能抛出的错误异常,极其发生的情况

　　@todo指明应该改进或没有实现的地方

　　@var定义说明变量/属性。

　　@version定义版本信息

?文档标记的使用范围是指该标记可以用来修饰的关键字，或其他文档标记。

　　所有的文档标记都是在每一行的 * 后面以@开头。如果在一段话的中间出来@的标记，这个标记将会被当做普通内容而被忽略掉。

　　@access

　　使用范围：class,function,var,define,module

　　该标记用于指明关键字的存取权限：private、public或proteced

　　@author

　　指明作者

　　@copyright

　　使用范围：class，function，var，define，module，use

　　指明版权信息

　　@deprecated

　　使用范围：class，function，var，define，module，constent，global，include

　　指明不用或者废弃的关键字

　　@example

　　该标记用于解析一段文件内容，并将他们高亮显示。Phpdoc会试图从该标记给的文件路径中读取文件内容

　　@const

　　使用范围：define

　　用来指明php中define的常量

　　@final

　　使用范围：class,function,var

　　指明关键字是一个最终的类、方法、属性，禁止派生、修改。

　　@filesource

　　和example类似，只不过该标记将直接读取当前解析的php文件的内容并显示。

　　@global

　　指明在此函数中引用的全局变量

　　@ingore

　　用于在文档中忽略指定的关键字

　　@license

　　相当于html标签中的<a>,首先是URL，接着是要显示的内容

　　例如<a href=”http://www.baidu.com”>百度</a>

　　可以写作 @license http://www.baidu.com 百度

　　@link

　　类似于license

　　但还可以通过link指到文档中的任何一个关键字

　　@name

　　为关键字指定一个别名。

　　@package

　　使用范围：页面级别的-> define，function，include

　　类级别的->class，var，methods

　　用于逻辑上将一个或几个关键字分到一组。

　　@abstrcut

　　说明当前类是一个抽象类

　　@param

　　指明一个函数的参数

　　@return

　　指明一个方法或函数的返回指

　　@static

　　指明关建字是静态的。

　　@var

　　指明变量类型

　　@version

　　指明版本信息

　　@todo

　　指明应该改进或没有实现的地方

　　@throws

　　指明此函数可能抛出的错误异常,极其发生的情况

　　上面提到过，普通的文档标记标记必须在每行的开头以@标记，除此之外，还有一种标记叫做inline tag,用{@}表示，具体包括以下几种：

　　{@link}

　　用法同@link

　　{@source}

　　显示一段函数或方法的内容

文档块是一种扩展了 C++ 风格的 PHP 注释，它以 "/**" 开始，并在每一行的行首有一个 "*" 。文档块 DocBlocks 位于被注释区域的前面，在文档块中，任何不以 * 开始的行将被忽略。
要注释 "foo()"，请将文档块放在紧挨着函数声明的前面：
/**
 * 这是一个文档块注释
 */
function foo()
{
}
下面的例子将会应用文档块到 "define('me',2);"，而不是 "function foo()":
/**
 * 函数 foo 的文档块？
 *
 * 不对，这是常量 me 的!
 */
define('me',2);
function foo($param = me)
{
}
define() 语句，函数，类，类方法，类变量，include() 语句和全局变量都可以被文档化。see Elements of the source code that can be documented
一个文档块通常会以如下的顺序包含三个基本片段：
短介绍
长描述
标签（Tags）
短介绍开始于第一行，以一个空行或一个句号（这里是指英文句号，下同）结束。单词中的句号（例如 example.com 或 0.1%）会被忽略。如果短介绍长度超过三行，则只有第一行有效。而长描述则以任意多行继续，而且可以包含 用于格式化显示的 HTML 标记。下面是一个带有短介绍和长描述的文档块：
/**
 * return the date of Easter
 * 
 * Using the formula from "Formulas that are way too complicated for anyone to
 * ever understand except for me" by Irwin Nerdy, this function calculates the
 * date of Easter given a date in the Ancient Mayan Calendar, if you can also
 * guess the birthday of the author.
 */
另外，你还可以把所有段落放在一对 <p></p> 标签中。要小心，如果第一段没有以一个 <p> 开头，phpDocumentor 将会假设文档块只是像下面这样使用简单的双换行符定义段落分割：
/**
 * 短介绍
 *
 * 长描述中的第一句开始于此，
 * 然后在这一行继续，
 * 最后在这一段的
 * 末尾结束
 *
 * 上面的空行表示一个新的段落分割
 */
这儿是一个使用 <p> 的例子：
/**
 * 短介绍
 *
 * <p>长描述中的第一句开始于此，
 * 然后在这一行继续，
 * 最后在这一段的
 * 末尾结束</p>
 * 这一行将被完全忽略！它并没有包含在 p 标签中
 * <p>这是一个新的段落</p>
 */
通过命令行选项 -j, --javadocdesc，phpDocumentor 也可以支持 JavaDoc 的文档块格式。由于不匹配的 p 标签不兼容 XHTML 标准，我们强烈建议你尽可能避免使用这种语法。
/**
 * <p>
 * Short desc is only to the first period.
 * This means a sentence like:
 * "Parses Mr./Mrs. out of $_GET." will
 * parse a short description of "Parses Mr."
 * which is rather silly.  Long description is
 * the entire DocBlock description including the
 * Short desc, and paragraphs begin where p is like:
 * <p>
 * The p above denotes a paragraph break
 */
phpDocumentor 会将长描述中所有的空白转换为单个空格。请使用断行定义新行，或者使用下一节中讨论的 <pre> 。
文档块描述细节[编辑]
在有的解析器中，文档块中的若干 HTML 标签可能会被解析以显示特定的信息。由于并非所有的HTML标签都是允许使用的，它们有可能被转换为普通文本或更加视具体内容而定的表情。例如，一个 <b> 标签可能会被转换为 <emphasis> 。
下面是 phpDocumentor 所支持的标签列表：
<b> -- emphasize/bold text
<code> -- Use this to surround php code, some converters will highlight it
<br> -- hard line break, may be ignored by some converters
<i> -- italicize/mark as important
<kbd> -- denote keyboard input/screen display
<li> -- list item
<ol> -- ordered list
<p> -- If used to enclose all paragraphs, otherwise it will be considered text
<pre> -- Preserve line breaks and spacing, and assume all tags are text (like XML's CDATA)
<samp> -- denote sample or examples (non-php)
<ul> -- unordered list
<var> -- denote a variable name
For the rare case when the text "<b>" is needed in a DocBlock, use a double delimiter as in <<b>>. phpDocumentor will automatically translate that to the physical text "<b>".
使用 <code> 和 <pre>[编辑]
<code> 和 <pre> 中的内容会忽略上述列表中的任何 HTML 标签。（当然，它们自己对应的关闭标签除外）
文档块模板[编辑]
文档块模板的目的是缩减重复的输入。例如，如果有大量的类成员变量是私有的，我们可以使用一个文档块模板标记它们的属性为私有。文档块模板就是简单地扩充了其中的普通文档块。
一个文档块模板是通过它头部的一个普通文档块识别的。下面是一个最基本的文档块模板：
/**#@+
 *
 */
将其标记为一个文档块模板的文本是 "/**#@+" - 嗯，6个字符都是必须存在的。文档块模板会一直应用到所有的可文档化的元素，直到出现模板结束标记：
/**#@-*/
注意，所有的8个字符必须呈现为 "/**#@-*/" ，这样 phpDocumentor 才会将其识别为一个模板。
页面级的文档块[编辑]
页面级的文档块是唯一一种无法把自己放在被注释元素之前的文档块。因为没有办法将注释放在一个文件的前面（非文档内容的前面）。为了解决这个问题，phpDocumentor 的方式是将一个文件中出现的符合某些条件的第一个文档块作为页面级文档块。
<?php
/**
 * 页面级文档块
 */
define('oops','不，它不是页面级文档块');
?>
上面的例子中有一个文档块，而且它是文件中出现的第一个文档块，但它不是一个页面级文档块。那么 phpDocumentor 是怎样区分页面级文档块和其他文档块的呢？简单：
<?php
/**
 * Pretend this is a file
 *
 * 这个是页面级文档块，因为它是文件中出现的第一个文档块，而且含有 @package 标签
 * @package pagepackage
 */
 define("almost","差不多了，这个页面级文档块是属于这个页面的，而这条 define 语句并没有文档块");
?>
在 1.2.2 版的 phpDocumentor 中，页面级的文档块就是文件中出现的第一个含有 @package 标签的文档块。然而，这个例子将会导致一个 WARNING 错误：Page-level DocBlock precedes "define almost", use another DocBlock to document the source element. 你可以通过在文档中对 define 语句添加类似下面的注释避免这个 WARNING：
<?php
/**
 * 页面级文档块
 * @package pagepackage
 */
/**
 * Define 文档块
 */
define("ahhhh","哈哈，现在，页面级文档块属于这个页面，“Define 文档块” 属于 define 语句");
?>
现在，页面级文档块属于这个页面，而 define 语句也有了自己的文档块。
So, 一个文档块仅在同时符合以下条件时，它才是一个页面级文档块：
文件中出现的第一个文档块
同时:包含一个 @package 标签，或者
立即跟上另一个其他 PHP 元素的文档块 (不推荐使用这种方式, 最好总是使用 @package 标签)
一个页面级文档块可以含有所有的普通 phpDocumentor 标签，以及下列标签：
@package
@subpackage
phpDocumentor 不会文档化像第一个例子中的文件，文件中必须有至少一个可文档化的 PHP 元素。