PHPDoc PHP注释的标准文档（翻译自Wiki）

浏览数：33 / 时间：2015年06月09日

文档注释，无非“//”和“/**/”两种，自己写代码，就那么点，适当写几句就好了；但是一个人总有融入团队的一天，团队的交流不是那几句注释和一张嘴能解决的，还需要通用的注释标准。

PHPDoc是PHP文档注释的一个标准，可以帮助我们在注释文档时有规范，查看别人的代码时更方便。下面的表格是我翻译的WIKI上的PHPDoc，个人英文水平有限，可以参照原文。

文档翻译自：http://en.wikipedia.org/wiki/Phpdoc

标记	用途	描述
@abstract		抽象类的变量和方法
@access	public, private or protected	文档的访问、使用权限. @access private 表明这个文档是被保护的。
@author	张三 <[email protected]>	文档作者
@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		文档、类、函数的版本信息

原文截图：

PHPDoc注释实例：

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

<?php 
 /**
  * start page for webaccess
  *
  * PHP version 5
  *
  * @category  PHP
  * @package   PSI_Web
  * @author    Michael Cramer <[email protected]>
  * @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 <[email protected]>
  * @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();
     }
 }
 ?>