編輯“WordPress:Inline Documentation”（章節(jié)）

== 函數(shù) PHPdoc ==

WordPress 函數(shù) PHPdoc類型包括短描述和長描述(如果適用的話).

短描述必須包括只帶括號(hào)'()'的函數(shù)名字。短描述不應(yīng)該重復(fù)說名函數(shù)名是什么，而應(yīng)該深入一些描述這個(gè)函數(shù)是做什么的(代碼)并作總結(jié)。函數(shù)名字可能表達(dá)了什么，但事實(shí)上做的卻是完全不同的東西(規(guī)格改變了但是用法沒有變)。



短描述要求完全考慮到這個(gè)函數(shù)的文獻(xiàn)資料。在特殊情況下可能會(huì)留下記錄，如下，讓人知道短描述丟失了。


長描述應(yīng)該包含在大多數(shù)的函數(shù)中，來清楚地給出短描述包含的意思。大多數(shù)情況下，摘要只是作為在長描述中編碼器讀取的提示。

極少情況下，函數(shù)非常的短，摘要就可以描述全部的函數(shù)目的范圍了。這取決于文獻(xiàn)資料作者的判斷，但是作為一個(gè)規(guī)則，應(yīng)該嘗試吧長描述包括到PHPdoc 模塊中去。 

<</pre>

如果函數(shù)沒有參數(shù)，或者返回資料留下短和長描述丟失的記錄，這是可以接受的。這只能在你為一個(gè)多重函數(shù)寫資料時(shí)，留下一個(gè)你專門為別人或者你自己留下空白以便將來完成的記錄時(shí)，才可以使用。

<pre>
/**
 * function_name() - {{@internal Missing Short Description}}}
 *
 * {{@internal Missing Long Description}}}
 *
 */
</pre>


對(duì)于其他提醒你或者你本不想留下空白的標(biāo)簽。其他時(shí)候，它應(yīng)該被認(rèn)為是有人故意留下空白，或者是不認(rèn)為描述對(duì)于別人理解函數(shù)是必須的。信息可能并不服務(wù)于某種目的，如果在別的地方也可以找到的話。如，在使用@uses標(biāo)簽時(shí)，如果全局變量已經(jīng)擁有資料時(shí)。

<pre> * @uses function_name() {{@internal Missing Description}}}</pre>

在短和長描述后，別的信息對(duì)于編碼器和phpDocumentor 站點(diǎn)也是很重要的。

<pre>
/**
 * function_name() - Short Description
 * 
 * Long Description
 *
 * @package WordPress
 * @since version
 *
 * @param    type    $varname    Description
 * @return   type                Description
 */
</pre>

@since的慣例是只使用版本號(hào)，"2.1"，或者"2.3.1"，并且停止其他的字符串。 @package 信息給出了編碼器和請(qǐng)求函數(shù)用的phpDocumentor，這樣@since 就會(huì)請(qǐng)求屬于它的版本號(hào)。

為了保持一致，如果參數(shù)可用，它們必須為每個(gè)函數(shù)建立資料文獻(xiàn)。如果"return" 關(guān)鍵詞在函數(shù)中的任何地方使用，那么@return標(biāo)簽應(yīng)該被用來建立可能的資料。 如果它不存在的話，最好就不要包含這個(gè)標(biāo)簽，因?yàn)槿绻嬖?，讀者可能希望它能有 "return" 這個(gè)關(guān)鍵詞。

如果函數(shù)被反對(duì)，就不應(yīng)該繼續(xù)使用了，然后會(huì)給出@deprecated 標(biāo)簽連同版本和使用哪些作為替代的描述。同樣包括帶有函數(shù)名字的@uses標(biāo)簽。

<pre>
/**
 * ... Descriptions
 *
 * @deprecated 2.1  Use function_name() instead.
 * @uses function_name()
 *
 * ... parameters and return descriptions
 */
</pre>