PHPDoc

title: PHPDoc 组件.
title: 文档块(DocBlock).
content: 文档块是一种扩展了 C++ 风格的 PHP 注释,它以 "/**" 开始,并在每一行的行首有一个 "*" 。文档块 DocBlocks 位于被注释区域的前面,在文档块中,任何不以 * 开始的行将被忽略。  要注释 "foo()",请将文档块放在紧挨着函数声明的前面:  下面的例子将会应用文档块到 "define('me',2);",而不是 "function foo()":  define() 语句,函数,类,类方法,类变量,include() 语句和全局变量都可以被文档化。see Elements of the source code that can be documented  一个文档块通常会以如下的顺序包含三个基本片段:  短介绍开始于第一行,以一个空行或一个句号(这里是指英文句号,下同)结束。单词中的句号(例如 example.com 或 0.1%)会被忽略。如果短介绍长度超过三行,则只有第一行有效。而长描述则以任意多行继续,而且可以包含 用于格式化显示的 HTML 标记。下面是一个带有短介绍和长描述的文档块:  另外,你还可以把所有段落放在一对 </p> 标签中。要小心,如果第一段没有以一个  开头,phpDocumentor 将会假设文档块只是像下面这样使用简单的双换行符定义段落分割:  这儿是一个使用  的例子:  通过命令行选项 -j, --javadocdesc,phpDocumentor 也可以支持 JavaDoc 的文档块格式。由于不匹配的 p 标签不兼容 XHTML 标准,我们强烈建议你尽可能避免使用这种语法。  phpDocumentor 会将长描述中所有的空白转换为单个空格。请使用断行定义新行,或者使用下一节中讨论的 <pre> 。
title: 文档块描述细节.
content: 在有的解析器中,文档块中的若干 HTML 标签可能会被解析以显示特定的信息。由于并非所有的HTML标签都是允许使用的,它们有可能被转换为普通文本或更加视具体内容而定的表情。例如,一个 <b> 标签可能会被转换为 <emphasis> 。  下面是 phpDocumentor 所支持的标签列表:  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>".
title: 使用 <code> 和 <pre>.
content: <code> 和 <pre> 中的内容会忽略上述列表中的任何 HTML 标签。(当然,它们自己对应的关闭标签除外)
title: 文档块模板.
content: 文档块模板的目的是缩减重复的输入。例如,如果有大量的类成员变量是私有的,我们可以使用一个文档块模板标记它们的属性为私有。文档块模板就是简单地扩充了其中的普通文档块。  一个文档块模板是通过它头部的一个普通文档块识别的。下面是一个最基本的文档块模板:  将其标记为一个文档块模板的文本是 "/**#@+" - 嗯,6个字符都是必须存在的。文档块模板会一直应用到所有的可文档化的元素,直到出现模板结束标记:  注意,所有的8个字符必须呈现为 "/**#@-*/",这样 phpDocumentor 才会将其识别为一个模板。
title: 页面级的文档块.
content: 页面级的文档块是唯一一种无法把自己放在被注释元素之前的文档块。因为没有办法将注释放在一个文件的前面(非文档内容的前面)。为了解决这个问题,phpDocumentor 的方式是将一个文件中出现的符合某些条件的第一个文档块作为页面级文档块。  上面的例子中有一个文档块,而且它是文件中出现的第一个文档块,但它不是一个页面级文档块。那么 phpDocumentor 是怎样区分页面级文档块和其他文档块的呢?简单:  在 1.2.2 版的 phpDocumentor 中,页面级的文档块就是文件中出现的第一个含有 @package 标签的文档块。然而,这个例子将会导致一个 WARNING 错误:Page-level DocBlock precedes "define almost", use another DocBlock to document the source element. 你可以通过在文档中对 define 语句添加类似下面的注释避免这个 WARNING:  现在,页面级文档块属于这个页面,而 define 语句也有了自己的文档块。  So, 一个文档块仅在同时符合以下条件时,它才是一个页面级文档块:  一个页面级文档块可以含有所有的普通 phpDocumentor 标签,以及下列标签:  phpDocumentor 不会文档化像第一个例子中的文件,文件中必须有至少一个可文档化的 PHP 元素。
title: 标签.
content: 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.  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
title: Packages.
content: 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:  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.

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

PHPDoc: PHPDoc is an adaptation of Javadoc for the PHP programming language. It is still an informal standard for commenting PHP code, but it is in the process of being formalized. It allows external document generators like phpDocumentor, which is the de facto standard implementation, to generate documentation of APIs and helps some IDEs such as Zend Studio, NetBeans, JetBrains PhpStorm, ActiveState Komodo Edit and IDE, PHPEdit and Aptana Studio to interpret variable types and other ambiguities in the loosely typed language and to provide improved code completion, type hinting and debugging.