PHPDoc 学习记录

https://zh.wikipedia.org/wiki/PHPDoc

PHPDoc 是一个 PHP 版的 Javadoc。它是一种注释 PHP 代码的正式标准。它支持通过类似 phpDocumentor 这样的外部文档生成器生成 API 文档，也可以帮助一些例如 Zend Studio,NetBeans, ActiveState Komodo Edit and IDE 和 Aptana Studio 之类的 集成开发环境 理解变量类型和弱类型语言中的其他歧义并提供改进的代码完成，类型提示和除错功能。

PHPDoc 可同时支持 面向对象 的和 面向过程的 代码。

文档块（DocBlock）[编辑]

文档块是一种扩展了 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, 一个文档块仅在同时符合以下条件时，它才是一个页面级文档块：

1. 文件中出现的第一个文档块
2. 同时:
   1. 包含一个 @package 标签，或者
   2. 立即跟上另一个其他 PHP 元素的文档块 (不推荐使用这种方式, 最好总是使用 @package 标签)

一个页面级文档块可以含有所有的普通 phpDocumentor 标签，以及下列标签：

• @package
• @subpackage

phpDocumentor 不会文档化像第一个例子中的文件，文件中必须有至少一个可文档化的 PHP 元素。

标签[编辑] //经常用到很重要

Tags are single words prefixed by a "@" symbol. Tags inform parsers how to present information and modify display of documentation as well as allow the IDE to define variable types. All tags are optional, but if you use a tag, they do have specific requirements to parse properly.

Common tags

Tag	Usage	Description
@abstract		Documents an abstract class, class variable or method.
@access	public, private or protected	Documents access control for an element. @access private indicates that documentation of element be prevented.
@author	author name <author@email>	Documents the author of the current element.
@copyright	name date	Documents copyright information.
@deprecated	version	Documents a method as deprecated.
@deprec		same as @deprecated
@example	/path/to/example	Documents the location of an external saved example file.
@exception		documents an exception thrown by a method — also see @throws.
@global	type $globalvarname	Documents a global variable or its use in a function or method.
@ignore		Prevents the documentation of an element
@internal		private information for advanced developers
@link	URL
@name	global variable name	Specifies an alias for a variable. For example, $GLOBALS['myvariable'] becomes $myvariable
@magic		phpDocumentor tags}-].
@package	name of a package	Documents a group of related classes and functions.
@param	type [$varname] description
@return	type description	This tag should not be used for constructors or methods defined with a void return type.
@see		Documents an association to another method or class.
@since	version	Documents when a method was added to a class.
@static		Documents a static class or method
@staticvar		Documents a static variable's use in a function or class
@subpackage
@throws		Documents an exception thrown by a method.
@todo		Documents things that need to be done to the code at a later date.
@var	type	a data type for a class variable
@version		Provides the version number of a class or method.