更多参考 http://phpdoc.org/docs/latest/index.html
在phpdocumentor中，注释分为文档性注释和非文档性注释。
所谓文档性注释，是那些放在特定关键字前面的多行注释，特定关键字是指能够被phpdoc分析的关键字，例如class，var等，具体的可参加附录1.
那些没有在关键字前面或者不规范的注释就称作非文档性注释，这些注释将不会被phpdoc所分析，也不会出现在你产生的api文当中。
3.2如何书写文档性注释:
所 有的文档性注释都是由/**开始的一个多行注释，在phpDocumentor里称为DocBlock, DocBlock是指软件开发人员编写的关于某个关键字的帮助信息，使得其他人能够通过它知道这个关键字的具体用途，如何使用。 PhpDocumentor规定一个DocBlock包含如下信息：
1. 功能简述区
2. 详细说明区
3. 标记tag
文档性注释的第一行是功能描述区，正文一般是简明扼要地说明这个类，方法或者函数的功能，功能简述的正文在生成的文档中将显示在索引区。功能描述区的内容可以通过一个空行或者 . 来结束
在 功能描述区后是一个空行，接着是详细说明区,. 这部分主要是详细说明你的API的功能，用途，如果可能，也可以有用法举例等等。在这部分，你应该着重阐明你的API函数或者方法的通常的用途，用法，并 且指明是否是跨平台的（如果涉及到），对于和平台相关的信息，你要和那些通用的信息区别对待，通常的做法是另起一行，然后写出在某个特定平台上的注意事项 或者是特别的信息，这些信息应该足够，以便你的读者能够编写相应的测试信息，比如边界条件，参数范围，断点等等。
之后同样是一个空白行，然后是文档的标记tag，指明一些技术上的信息，主要是最主要的是调用参数类型，返回值极其类型，继承关系，相关方法/函数等等。
文档注释中还可以使用例如<b> <code>这样的标签
文档标记的使用范围是指该标记可以用来修饰的关键字，或其他文档标记。
所有的文档标记都是在每一行的 * 后面以@开头。如果在一段话的中间出来@的标记，这个标记将会被当做普通内容而被忽略掉。
6．一些注释规范
a.注释必须是
/**
* XXXXXXX
*/
的形式
b.对于引用了全局变量的函数，必须使用glboal标记。
c.对于变量，必须用var标记其类型（int,string,bool...）
d.函数必须通过param和return标记指明其参数和返回值
e.对于出现两次或两次以上的关键字，要通过ingore忽略掉多余的，只保留一个即可
f.调用了其他函数或类的地方，要使用link或其他标记链接到相应的部分，便于文档的阅读。
g.必要的地方使用非文档性注释，提高代码易读性。
h.描述性内容尽量简明扼要，尽可能使用短语而非句子。
i.全局变量，静态变量和常量必须用相应标记说明
1 <?php 2 /** 3 * @name 名字 4 * @abstract 申明变量/类/方法 5 * @access 指明这个变量、类、函数/方法的存取权限 6 * @author 函数作者的名字和邮箱地址 7 * @category 组织packages 8 * @copyright 指明版权信息 9 * @const 指明常量 10 * @deprecate 指明不推荐或者是废弃的信息MyEclipse编码设置 11 * @example 示例 12 * @exclude 指明当前的注释将不进行分析，不出现在文挡中 13 * @final 指明这是一个最终的类、方法、属性，禁止派生、修改。 14 * @global 指明在此函数中引用的全局变量 15 * @include 指明包含的文件的信息 16 * @link 定义在线连接 17 * @module 定义归属的模块信息 18 * @modulegroup 定义归属的模块组 19 * @package 定义归属的包的信息 20 * @param 定义函数或者方法的参数信息 21 * @return 定义函数或者方法的返回信息 22 * @see 定义需要参考的函数、变量，并加入相应的超级连接。 23 * @since 指明该api函数或者方法是从哪个版本开始引入的 24 * @static 指明变量、类、函数是静态的。 25 * @throws 指明此函数可能抛出的错误异常,极其发生的情况 26 * @todo 指明应该改进或没有实现的地方 27 * @var 定义说明变量/属性。 28 * @version 定义版本信息 29 */ 30 function XXX($a){..}
<?php /** * Sample File 2, phpDocumentor Quickstart * * This file demonstrates the rich information that can be included in * in-code documentation through DocBlocks and tags. * @author Greg Beaver <cellog@php.net> * @version 1.0 * @package sample */ //PHP code /** * A sample function docblock * @global string document the fact that this function uses $_myvar * @staticvar integer $staticvar this is actually what is returned * @param string $param1 name to declare * @param string $param2 value of the name * @return integer */ function firstFunc($param1, $param2 = ‘optional‘) { static $staticvar = 7; global $_myvar; return $staticvar; }
