转自：PHP经验——PHPDoc PHP注释的标准文档（翻译自Wiki）
文档注释，无非“//”和“/**/”两种 ，自己写代码，就那么点，适当写几句就好了；但是一个人总有融入团队的一天，团队的交流不是那几句注释和一张嘴能解决的，还需要通用的注释标准。
PHPDoc是PHP文档注释的一个标准，可以帮助我们在注释文档时有规范，查看别人的代码时更方便。下面的表格是我翻译的WIKI上的PHPDoc，个人英文水平有限，可以参照原文。
文档翻译自：http://en.wikipedia.org/wiki/Phpdoc
相关参考资料：
http://manual.phpdoc.org/HTMLSmartyConverter/PHP/li_phpDocumentor.html
http://www.ibm.com/developerworks/cn/linux/sdk/php/pear3/index.html
http://www.phpdoc.org/docs/latest/index.html
http://blog.csdn.net/eric6/article/details/5888894
PHPDoc注释标记说明：
| 标记 | 用途 | 描述 |
|---|---|---|
| @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 | 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 | phpdoc.de compatibility "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.[citation needed] |
| @see | element | Documents an association to any element (global variable, include, page, class, function, define, method, variable). |
| @since | version | Documents when a method was added to a class. |
| @static | Documents a static class or method | |
| @staticvar | type | 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. |
PHPDoc注释示例：
<?php /** * start page for webaccess * * PHP version 5 * * @category PHP * @package PSI_Web * @author Michael Cramer <BigMichi1@users.sourceforge.net> * @copyright 2009 phpSysInfo * @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License * @version SVN: $Id: class.Webpage.inc.php 412 2010-12-29 09:45:53Z Jacky672 $ * @link http://phpsysinfo.sourceforge.net */ /** * generate the dynamic webpage * * @category PHP * @package PSI_Web * @author Michael Cramer <BigMichi1@users.sourceforge.net> * @copyright 2009 phpSysInfo * @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License * @version Release: 3.0 * @link http://phpsysinfo.sourceforge.net */ class Webpage extends Output implements PSI_Interface_Output { /** * configured language * * @var String */ private $_language; /** * configured template * * @var String */ private $_template; /** * all available templates * * @var Array */ private $_templates = array(); /** * all available languages * * @var Array */ private $_languages = array(); /** * check for all extensions that are needed, initialize needed vars and read config.php */ public function __construct() { parent::__construct(); $this->_getTemplateList(); $this->_getLanguageList(); } /** * checking config.php setting for template, if not supportet set phpsysinfo.css as default * checking config.php setting for language, if not supported set en as default * * @return void */ private function _checkTemplateLanguage() { $this->_template = trim(PSI_DEFAULT_TEMPLATE); if (!file_exists(APP_ROOT.'/templates/'.$this->_template.".css")) { $this->_template = 'phpsysinfo'; } $this->_language = trim(PSI_DEFAULT_LANG); if (!file_exists(APP_ROOT.'/language/'.$this->_language.".xml")) { $this->_language = 'en'; } } /** * get all available tamplates and store them in internal array * * @return void */ private function _getTemplateList() { $dirlist = CommonFunctions::gdc(APP_ROOT.'/templates/'); sort($dirlist); foreach ($dirlist as $file) { $tpl_ext = substr($file, strlen($file) - 4); $tpl_name = substr($file, 0, strlen($file) - 4); if ($tpl_ext === ".css") { array_push($this->_templates, $tpl_name); } } } /** * get all available translations and store them in internal array * * @return void */ private function _getLanguageList() { $dirlist = CommonFunctions::gdc(APP_ROOT.'/language/'); sort($dirlist); foreach ($dirlist as $file) { $lang_ext = substr($file, strlen($file) - 4); $lang_name = substr($file, 0, strlen($file) - 4); if ($lang_ext == ".xml") { array_push($this->_languages, $lang_name); } } } /** * render the page * * @return void */ public function run() { $this->_checkTemplateLanguage(); $tpl = new Template("/templates/html/index_dynamic.html"); $tpl->set("template", $this->_template); $tpl->set("templates", $this->_templates); $tpl->set("language", $this->_language); $tpl->set("languages", $this->_languages); echo $tpl->fetch(); } } ?>