PHP註釋的藝術——phpDoc規範

用過IDE或看過其餘源碼的小夥伴們應該都見過相似下面這樣的註釋

 

/** * 遞歸獲取全部遊戲分類 * @param int $id * @return array */

看得多了就大概知道了一些規律。爲了使本身的代碼更加規zhuang範bi，也開始有樣學樣地寫着這些註釋

其實這種註釋格式是有本身的名字的，它就叫——

PHPDOC

PHPDoc 是一個 PHP 版的 Javadoc。它是一種註釋 PHP 代碼的正式標準。它支持經過相似 phpDocumentor 這樣的外部文檔生成器生成 API 文檔，也能夠幫助一些例如 Zend Studio, NetBeans, ActiveState Komodo Edit and IDE 和 Aptana Studio 之類的 集成開發環境 理解變量類型和弱類型語言中的其餘歧義並提供改進的代碼完成，類型提示和除錯功能。
PHPDoc 可同時支持 面向對象 的和 面向過程的 代碼。

以上摘自維基百科
簡單來講PHPDOC能夠用來自動生成API文檔。主流的IDE都會識別它，並在你coding中給予你相應的智能提示。使用PHPDOC有如下好處

• 讓你的代碼更加規zhuang範bi，更易於理解

• 讓你的IDE更懂你的代碼，更加智能的提示和自動完成

• 如需API手冊，可以使用phpDocumentor來自動生成

還等什麼？快跟我一塊兒來學習又好用又有逼格的phpDoc吧！

有關phpDoc的完整文檔位於phpDocumentor官網。如下內容由我我的理解、提煉而來，並且我也還在學習中，若有失誤還請各位多多指教

@api

表示這是一個提供給第三方使用的API接口

@author

做者
格式@author [名稱] [<郵箱>]
例如@author mokeyjay <i@mokeyjay.com>

@copyright

版權聲明。例如不少網站底部都有
格式@copyright [描述]
例如@copyright 1949-2016 China

@deprecated

不建議使用的、已過時的、將被刪除的
格式@deprecated [<版本號>] [<描述>]
例如@deprecated 1.0.0 新版本將再也不包含此函數
若是它是被其餘方法所取代了，建議添加@see標記

@example

例子、示例、用例。也可表示方法返回值的例子
格式@example [位置] [<起始行號> [<行數>] ] [<描述>]
例如@example demo.php 10 3 使用示例

@filesource

沒看懂，若是大家看懂了請告訴我。傳送門

@global

全局變量
格式@global [類型][名稱] @global [類型][描述]
我懷疑這裏是源文檔打錯了，大概應該是
格式@global [類型][名稱][描述]
類型@global string name 用戶名

@ignore

忽略
格式@ignore [<描述>]
例如你在if和else的語句塊中定義分別同一個變量但值不一樣時，能夠經過此標記讓phpDocumentor忽略其中一個，以避免生成重複的文檔。例如

if ($ostest) { /** * This define will either be 'Unix' or 'Windows' */ define("OS","Unix"); } else { /** * @ignore */ define("OS","Windows"); }

@internal

僅限內部使用的
格式@internal [描述]
例如@internal 僅限內部測試使用

@license

協議，很常見的啦
格式@license [<url>] [名稱]
例如@license GPL

@link

連接，可用於輔助說明、引用文檔等
格式@link [url] [<描述>]
例如@link http://g.cn 不懂滾去問谷歌，別來煩我

@method

方法。這是用在類註釋裏的標記。特別適合一些動態加載的類，IDE沒法自動提示出來，這時就能夠經過寫@method標記來告訴IDE我這類裏有哪些方法
格式@method [返回值類型] [名稱]([[類型] [參數]<, ...>]) [<描述>]
例如@method string google(string $question) 向谷歌提問，返回答案內容

@package

包。但php沒有包，因此就用來表示命名空間
例如@package yii\base\db

@param

參數，用於函數和方法註釋裏的標記
格式@param [Type] [name] [<description>]
例如@param string title 文章標題

@property

類屬性，與@method相似，能夠告訴IDE我這類裏有哪些屬性
格式@property [Type] [name] [<description>]
例如@property int id 用戶id

@property-read

只讀的屬性。例如__get魔術方法可以取到的屬性
格式@property-read [Type] [name] [<description>]
例如@property-read int id 用戶id

@property-write

只可寫的屬性。例如__set魔術方法可以設置的屬性
格式@property-write [Type] [name] [<description>]
例如@property-write string name 用戶名

@return

返回值
格式@return [類型] [<描述>]]
例如@return array 結果數組

@see

參考，相似@link，可與@deprecated聯動
格式@see [url或完整方法名] [<描述>]
例如@see \yii\base\db::tableName() 舊方法table_name已棄用，請使用此方法替代

@since

從xx版本開始。例如從1.0以後添加了xx功能、刪除了xx參數等
格式@since [1.0.0] [<描述>]
例如@since 1.0.2 添加了$b參數

@source

沒看懂，若是大家看懂了請告訴我。傳送門

@throws

可能會拋出的錯誤類型
格式@throws [類型] [<描述>]
例如@throws LifeException 沒錢了，好想死啊

@todo

待辦。提示本身或他人還須要作些什麼
格式@todo [描述]
例如@todo 這個類還沒作異常處理

@uses

使用
格式@uses [完整方法名] [<描述>]
例如@uses \yii\base\db::$count 使用此屬性計數

@var

變量
格式@var [類型] [變量名] [<描述>]
例如@var int id 用戶id

@version

版本號
格式@version [<載體>] [<描述>]
例如@version 1.0.1 2016-07-03更新
或者@version GIT:1f3197d01 來自GIT分支1f3197d01