PHPDocument是从你的源代码的注释中生成文档，因此在给你的程序做注释的过程，也就是你编制文档的过程。

从这一点上讲，PHPdoc促使你要养成良好的编程习惯，尽量使用规范，清晰文字为你的程序做注释，同时多多少少也避免了事后编制文档和文档的更新不同步的一些问题。

在phpdocumentor中，注释分为文档性注释和非文档性注释。

所谓文档性注释，是那些放在特定关键字前面的多行注释，特定关键字是指能够被phpdoc分析的关键字，例如class，var等，具体的可参加附录1.

那些没有在关键字前面或者不规范的注释就称作非文档性注释，这些注释将不会被phpdoc所分析，也不会出现在你产生的api文当中。

所有的文档性注释都是由/**开始的一个多行注释，在phpDocumentor里称为DocBlock, DocBlock是指软件开发人员编写的关于某个关键字的帮助信息，使得其他人能够通过它知道这个关键字的具体用途，如何使用。 PhpDocumentor规定一个DocBlock包含如下信息：

1. 功能简述区

2. 详细说明区

3. 标记tag

文档性注释的第一行是功能描述区，正文一般是简明扼要地说明这个类，方法或者函数的功能，功能简述的正文在生成的文档中将显示在索引区。功能描述区的内容可以通过一个空行或者 . 来结束在功能描述区后是一个空行，接着是详细说明区,. 这部分主要是详细说明你的API的功能，用途，如果可能，也可以有用法举例等等。在这部分，你应该着重阐明你的API函数或者方法的通常的用途，用法，并且指明是否是跨平台的（如果涉及到），对于和平台相关的信息，你要和那些通用的信息区别对待，通常的做法是另起一行，然后写出在某个特定平台上的注意事项或者是特别的信息，这些信息应该足够，以便你的读者能够编写相应的测试信息，比如边界条件，参数范围，断点等等。

之后同样是一个空白行，然后是文档的标记tag，指明一些技术上的信息，主要是最主要的是调用参数类型，返回值极其类型，继承关系，相关方法/函数等等。

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

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

标记一览:
标记 用途 描述

@abstract           抽象类的变量和方法
@access     public, private or protected     文档的访问、使用权限. @access private 表明这个文档是被保护的。
@author     张三 <zhangsan@163.com>     文档作者
@copyright     名称 时间     文档版权信息
@deprecated     version     文档中被废除的方法
@deprec           同 @deprecated
@example     /path/to/example     文档的外部保存的示例文件的位置。
@exception           文档中方法抛出的异常，也可参照 @throws.
@global     类型：$globalvarname     文档中的全局变量及有关的方法和函数
@ignore           忽略文档中指定的关键字
@internal           开发团队内部信息
@link     URL     类似于license 但还可以通过link找到文档中的更多个详细的信息
@name     变量别名     为某个变量指定别名
@magic           phpdoc.de compatibility
@package     封装包的名称     一组相关类、函数封装的包名称
@param     如 [$username] 用户名     变量含义注释
@return     如 返回bool     函数返回结果描述，一般不用在void（空返回结果的）的函数中
@see     如 Class Login（）     文件关联的任何元素（全局变量，包括，页面，类，函数，定义，方法，变量）。
@since     version     记录什么时候对文档的哪些部分进行了更改
@static           记录静态类、方法
@staticvar           在类、函数中使用的静态变量
@subpackage           子版本
@throws           某一方法抛出的异常
@todo           表示文件未完成或者要完善的地方
@var     type     文档中的变量及其类型
@version           文档、类、函数的版本信息

标记tag:

1    <b>
2    <code>
3    <br>
4    <kdb>
5    <li>
6    <pre>
7    <ul>
8    <samp>
9    <var>

一些注释规范

1.注释必须是如下形式:

/**
  * XXXXXXX
  */

2.对于引用了全局变量的函数，必须使用glboal标记。

3.对于变量，必须用var标记其类型（int,string,bool...）

4.函数必须通过param和return标记指明其参数和返回值

5.对于出现两次或两次以上的关键字，要通过ingore忽略掉多余的，只保留一个即可

6.调用了其他函数或类的地方，要使用link或其他标记链接到相应的部分，便于文档的阅读。

7.必要的地方使用非文档性注释，提高代码易读性。

8.描述性内容尽量简明扼要，尽可能使用短语而非句子。

9.全局变量，静态变量和常量必须用相应标记说明