[php]PHP注释的标准文档写得非常好的文档范例（翻译自Wiki）PHPD

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

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

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

原文截图：

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(); 
     } 
 } 
 ?>