PHP經驗——PHPDoc PHP注釋的標准文檔（翻譯自Wiki）

文檔注釋，無非“//”和“/**/”兩種 ，自己寫代碼，就那么點，適當寫幾句就好了；但是一個人總有融入團隊的一天，團隊的交流不是那幾句注釋和一張嘴能解決的，還需要通用的注釋標准。

PHPDoc是PHP文檔注釋的一個標准，可以幫助我們在注釋文檔時有規范，查看別人的代碼時更方便。下面的表格是我翻譯的WIKI上的PHPDoc，個人英文水平有限，可以參照原文。

文檔翻譯自：http://en.wikipedia.org/wiki/Phpdoc

標記	用途	描述
@abstract		抽象類的變量和方法
@access	public, private or protected	文檔的訪問、使用權限. @access private 表明這個文檔是被保護的。
@author	張三 <[e-mail]>	文檔作者
@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注釋實例：

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