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

轉自：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		Team Dev內部資訊
@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		文檔、類、函數的版本資訊

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

英文說明：

Common tags

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