PHPDoc

Posted on by 技安PHPDoc已关闭评论

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

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

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.

In addition, some parsers allow two addition inline tags: {@id}, used to allow direct linking to sections in a tutorial, and {@toc}, used to generate a table of contents from {@id}s in the file. Think of {@id} like an <a name=”idname”> HTML tag as it serves the same function.

For more in depth discussion of PHPDoc tags, see http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.pkg.html

Packages

To understand the role of packages and how to use @package, it is important to know the logic behind packaging in PHP. The quest for structured programming led to the invention of functions, then classes, and finally packages. Traditionally, a re-usable software module was a collection of variables, constants and functions that could be used by another software package. PHP is an example of this model, as there are many extensions that consist of constants and functions like the tokenizer extension. One can think of the tokenizer extension as a package: it is a complete set of data, variables and functions that can be used in other programs. A more structured format of this model is of course objects, or classes. A class contains variables and functions. A single class packages together related functions and variables to be re-used.

phpDocumentor defines package in two ways:

  • Functions, Constants and Global Variables are grouped into files (by the filesystem), which are in turn grouped into packages using the @package tag in a page-level DocBlock
  • Methods and Class Variables are grouped into classes (by PHP), which are in turn grouped into packages in a Class DocBlock

These two definitions of package are exclusive. In other words, it is possible to have classes of a different package of the file that contains it.

文档标记：

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

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

@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}

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