用過(guò)IDE或看過(guò)其他源碼的小伙伴們應(yīng)該都見(jiàn)過(guò)類(lèi)似下面這樣的注釋

/**
 * 遞歸獲取所有游戲分類(lèi)
 * @param int $id
 * @return array
 */

看得多了就大概知道了一些規(guī)律。為了使自己的代碼更加規(guī)zhuang范bi，也開(kāi)始有樣學(xué)樣地寫(xiě)著這些注釋

其實(shí)這種注釋格式是有自己的名字的，它就叫——

PHPDOC

PHPDoc 是一個(gè) PHP 版的 Javadoc。它是一種注釋 PHP 代碼的正式標(biāo)準(zhǔn)。它支持通過(guò)類(lèi)似 phpDocumentor 這樣的外部文檔生成器生成 API 文檔，也可以幫助一些例如 Zend Studio, NetBeans, ActiveState Komodo Edit and IDE 和 Aptana Studio 之類(lèi)的 集成開(kāi)發(fā)環(huán)境 理解變量類(lèi)型和弱類(lèi)型語(yǔ)言中的其他歧義并提供改進(jìn)的代碼完成，類(lèi)型提示和除錯(cuò)功能。
PHPDoc 可同時(shí)支持 面向?qū)ο?的和 面向過(guò)程的 代碼。

以上摘自維基百科
簡(jiǎn)單來(lái)說(shuō)PHPDOC可以用來(lái)自動(dòng)生成API文檔。主流的IDE都會(huì)識(shí)別它，并在你coding中給予你相應(yīng)的智能提示。使用PHPDOC有以下好處

• 讓你的代碼更加規(guī)zhuang范bi，更易于理解

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

• 如需API手冊(cè)，可使用phpDocumentor來(lái)自動(dòng)生成

還等什么？快跟我一起來(lái)學(xué)習(xí)又好用又有逼格的phpDoc吧！

有關(guān)phpDoc的完整文檔位于phpDocumentor官網(wǎng)。以下內(nèi)容由我個(gè)人理解、提煉而來(lái)，而且我也還在學(xué)習(xí)中，如有失誤還請(qǐng)各位多多指教

@api

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

@author

作者
格式@author [名稱(chēng)] [<郵箱>]
例如@author mokeyjay <i@mokeyjay.com>

@copyright

版權(quán)聲明。例如很多網(wǎng)站底部都有
格式@copyright [描述]
例如@copyright 1949-2016 China

@deprecated

不建議使用的、已過(guò)期的、將被刪除的
格式@deprecated [<版本號(hào)>] [<描述>]
例如@deprecated 1.0.0 新版本將不再包含此函數(shù)
如果它是被其他方法所取代了，建議添加@see標(biāo)記

@example

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

@filesource

沒(méi)看懂，如果你們看懂了請(qǐng)告訴我。傳送門(mén)

@global

全局變量
格式@global [類(lèi)型][名稱(chēng)] @global [類(lèi)型][描述]
我懷疑這里是源文檔打錯(cuò)了，大概應(yīng)該是
格式@global [類(lèi)型][名稱(chēng)][描述]
類(lèi)型@global string name 用戶(hù)名

@ignore

忽略
格式@ignore [<描述>]
例如你在if和else的語(yǔ)句塊中定義分別同一個(gè)變量但值不同時(shí)，可以通過(guò)此標(biāo)記讓phpDocumentor忽略其中一個(gè)，以免生成重復(fù)的文檔。例如

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

@internal

僅限內(nèi)部使用的
格式@internal [描述]
例如@internal 僅限內(nèi)部測(cè)試使用

@license

協(xié)議，很常見(jiàn)的啦
格式@license [<url>] [名稱(chēng)]
例如@license GPL

@link

鏈接，可用于輔助說(shuō)明、引用文檔等
格式@link [url] [<描述>]
例如@link http://g.cn 不懂滾去問(wèn)谷歌，別來(lái)煩我

@method

方法。這是用在類(lèi)注釋里的標(biāo)記。特別適合一些動(dòng)態(tài)加載的類(lèi)，IDE無(wú)法自動(dòng)提示出來(lái)，這時(shí)就可以通過(guò)寫(xiě)@method標(biāo)記來(lái)告訴IDE我這類(lèi)里有哪些方法
格式@method [返回值類(lèi)型] [名稱(chēng)]([[類(lèi)型] [參數(shù)]<, ...>]) [<描述>]
例如@method string google(string $question) 向谷歌提問(wèn)，返回答案內(nèi)容

@package

包。但php沒(méi)有包，所以就用來(lái)表示命名空間
例如@package yii\base\db

@param

參數(shù)，用于函數(shù)和方法注釋里的標(biāo)記
格式@param [Type] [name] [<description>]
例如@param string title 文章標(biāo)題

@property

類(lèi)屬性，與@method類(lèi)似，可以告訴IDE我這類(lèi)里有哪些屬性
格式@property [Type] [name] [<description>]
例如@property int id 用戶(hù)id

@property-read

只讀的屬性。例如__get魔術(shù)方法能夠取到的屬性
格式@property-read [Type] [name] [<description>]
例如@property-read int id 用戶(hù)id

@property-write

只可寫(xiě)的屬性。例如__set魔術(shù)方法能夠設(shè)置的屬性
格式@property-write [Type] [name] [<description>]
例如@property-write string name 用戶(hù)名

@return

返回值
格式@return [類(lèi)型] [<描述>]]
例如@return array 結(jié)果數(shù)組

@see

參考，類(lèi)似@link，可與@deprecated聯(lián)動(dòng)
格式@see [url或完整方法名] [<描述>]
例如@see \yii\base\db::tableName() 舊方法table_name已棄用，請(qǐng)使用此方法替代

@since

從xx版本開(kāi)始。例如從1.0之后添加了xx功能、刪除了xx參數(shù)等
格式@since [1.0.0] [<描述>]
例如@since 1.0.2 添加了$b參數(shù)

@source

沒(méi)看懂，如果你們看懂了請(qǐng)告訴我。傳送門(mén)

@throws

可能會(huì)拋出的錯(cuò)誤類(lèi)型
格式@throws [類(lèi)型] [<描述>]
例如@throws LifeException 沒(méi)錢(qián)了，好想死啊

@todo

待辦。提示自己或他人還需要做些什么
格式@todo [描述]
例如@todo 這個(gè)類(lèi)還沒(méi)做異常處理

@uses

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

@var

變量
格式@var [類(lèi)型] [變量名] [<描述>]
例如@var int id 用戶(hù)id

@version

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

最新評(píng)論