WordPress:Inline Documentation

本頁(yè)面是添加內(nèi)嵌文檔到WordPress核心代碼來(lái)幫助將來(lái)的發(fā)展，改進(jìn)和更新的起點(diǎn)，同樣也是在學(xué)習(xí)PHP 和 WordPress時(shí)幫助別人。

本頁(yè)面以及后來(lái)的子頁(yè)面意味這開(kāi)發(fā)標(biāo)準(zhǔn)方法和格式，也是為了保證沒(méi)有副作用。在最好的情況下，內(nèi)嵌文檔應(yīng)該出現(xiàn)在靠近這個(gè)PEAR 樣本的地方。

什么應(yīng)該備有資料文獻(xiàn)[ ]

備份phpDocumentor的資料文獻(xiàn)，和其他關(guān)于global如何使用的閱讀源代碼。它不是必需的，而且在大多數(shù)時(shí)候都不是必需的，因?yàn)楹诵拈_(kāi)發(fā)人員可能不能接受這個(gè)補(bǔ)丁。函數(shù)和類(lèi)方法在沒(méi)有上下文環(huán)境的時(shí)候很難使用。文件可以提供上下文，但是內(nèi)嵌文檔不應(yīng)該用來(lái)給出極端的例子，除非在codex 信息不能立即獲得的小行代碼中。

多數(shù)WordPress中使用的類(lèi)都是單獨(dú)的(全部的功能包含在一個(gè)單獨(dú)的類(lèi)中), 但是通常要求手動(dòng)初始化屬性。大多數(shù)情況下什么時(shí)候在類(lèi)中使用方法是不清楚的。

新的附加類(lèi)和一些外部的庫(kù)使用多種類(lèi)來(lái)組成有某種功能的庫(kù)。這創(chuàng)建了一個(gè)更高的學(xué)習(xí)曲線，因?yàn)榛?lèi)(開(kāi)發(fā)者用來(lái)提供從所有其他類(lèi)獲得其功能的類(lèi)) 不清楚。給類(lèi)所在的類(lèi)庫(kù)層次中添加文檔會(huì)提供更高的清晰度。

為了類(lèi)資料的完整性，類(lèi)的屬性需要備有資料文獻(xiàn)。用于這功能的PHPdoc 標(biāo)簽可以在主頁(yè)找到，例子可以在下面找到。

PHPdoc標(biāo)簽[ ]

PHPDoc 標(biāo)簽和一些編輯器一起顯示更多有關(guān)于一段代碼的信息。對(duì)開(kāi)發(fā)者使用那些編輯器來(lái)了解目標(biāo)是什么以及在他們的代碼中能在什么地方使用是很有用的。

允許PHPdoc 模塊的慣例是含有@since 信息(盡管目前不可用)和@package信息, 必須是"WordPress"，除非是一個(gè)外部庫(kù)。

/**
 * ... Description(s) here
 *
 * @package WordPress
 * @since 2.1 or {{@internal Unknown}}}
 *
 * ... More information if needed.
 */

在函數(shù)和方法模塊內(nèi)不能使用PHPdoc注釋模塊，除非提供 "TODO" 信息。所有其他的方法和函數(shù)內(nèi)不能使用PHPdoc注釋。

/**
 * @todo ... Description
 */

Or the second form can be used is most cases.

/** @todo ... Description */

映射Includes 和Requires[ ]

為includes和requires準(zhǔn)備資料文獻(xiàn)，對(duì)于解釋包括的文件和現(xiàn)有的文件有什么關(guān)系，以及為什么需要它和在它里面能找到些什么是很有用的。

對(duì)于WordPress核心文件來(lái)說(shuō)并不是必需的，但是如果你吧代碼分成邏輯文件的話，可能對(duì)你的插件很有用。

/** 
 * This file holds all of the users
 * custom information
 */
require ABSPATH.'/wp-config.php';

文件資料[ ]

文件資料使用PHPdoc注釋模塊，可以用來(lái)給出一個(gè)關(guān)于在文件中有什么內(nèi)容和能找到什么東西的總覽。充分使用它的優(yōu)點(diǎn)可以阻止過(guò)于深入的查看文件和防止浪費(fèi)時(shí)間。

一些PHPdoc標(biāo)簽可以為phpDocumentor站點(diǎn)全局應(yīng)用到其他每一個(gè)PHPdoc 注釋模塊中。

/**
 * ... Description of what is contained in file here
 *
 * @package WordPress
 */

全局PHPdoc注釋模塊[ ]

它對(duì)于準(zhǔn)備一般用于函數(shù)@uses參數(shù)的全局資料通常是有用的。

先得到描述信息，因?yàn)槟鞘蔷幋a器所需要的。其他的信息也許也重要，用@since舉例，@ global標(biāo)簽只對(duì)phpDocumentator站點(diǎn)有用。

/**
 * ... Description 
 * @since
 * @global    type    $varname
 */

函數(shù) PHPdoc[ ]

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

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

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

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

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

<

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

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

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

 * @uses function_name() {{@internal Missing Description}}}

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

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

@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)該被用來(lái)建立可能的資料。如果它不存在的話，最好就不要包含這個(gè)標(biāo)簽，因?yàn)槿绻嬖冢x者可能希望它能有 "return" 這個(gè)關(guān)鍵詞。

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

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

類(lèi)PHPdoc 標(biāo)簽[ ]

關(guān)于類(lèi)PHPdoc標(biāo)簽的在WordPress類(lèi)中使用的信息是故意刪除的。注意類(lèi)的定義，屬性（變量），和類(lèi)方法（函數(shù)）都需要建立文獻(xiàn)資料。

PEAR 樣本應(yīng)該用來(lái)作為這些標(biāo)簽的使用的參考。

過(guò)去的 WP-Hackers 討論[ ]

WP-Hackers列表有大量過(guò)去的關(guān)于添加內(nèi)嵌文檔的討論。在最近的一些案例中，這個(gè)頁(yè)面無(wú)法在討論中引用或者被發(fā)現(xiàn)。通過(guò)給WordPress文件建立資料，關(guān)于WP-Hackers和別的東西的討論可以結(jié)束了，如果足夠的努力放到給這些文件建立檔案文獻(xiàn)的話。

內(nèi)嵌文檔 (February 2006)
PATCH 文檔 (February 2006)
函數(shù)注釋約定建議 (October 2007)

資源[ ]

英文版
phpDocumentor –為php語(yǔ)言自動(dòng)建立檔案的工具 (phpdoc.org)
phpDocumentor 指南 – 如何使用 phpDocumentor (phpdoc.org)
Zend 工作室 - PHP 開(kāi)發(fā)環(huán)境 (商業(yè)產(chǎn)品)
在 aptana.tv 有一個(gè)視頻展示出適當(dāng)?shù)膬?nèi)嵌文檔的力量. 一些標(biāo)簽就如你在那看到的一樣，非常有用。

擁有內(nèi)嵌文檔的文件[ ]

想得到一個(gè)WordPress中現(xiàn)有文件的列表，參見(jiàn)WordPress:WordPress 文件.

外部庫(kù)文件[ ]

第三方的庫(kù)應(yīng)該有文件級(jí)別的資料，但是不應(yīng)該成為WordPress文檔資料的一部分。下面這些第三方文件都擁有文件級(jí)別的資料。下面是WordPress 2.5 中的外部文件列表(1/10/2008).

所有的外部庫(kù)文件都完成了

/wp-includes/atomlib.php
/wp-includes/class-IXR.php
/wp-includes/class-phpass.php
/wp-includes/class-phpmailer.php (不需要文件級(jí)別的資料，因?yàn)樗蓄?lèi)級(jí)別的資料)
/wp-includes/class-pop3.php
/wp-includes/class-smtp.php (不需要文件級(jí)別的資料，因?yàn)樗蓄?lèi)級(jí)別的資料)
/wp-includes/class-snoopy.php
/wp-includes/gettext.php
/wp-includes/streams.php
/wp-includes/rss.php
/wp-includes/rss-functions.php (deprecated)

WordPress 完成的文件[ ]

這些文件已經(jīng)完成了PHPdoc 樣式資料。列出的部分是資料作者，連同 WordPress Trac ticket 號(hào)碼。

#5211 - /wp-settings.php - Jacob Santos (作為其他文件的示例使用)
#4393 - /wp-includes/author-template.php - Robin Adrianse 和清除 by Jacob Santos
#5523 - /wp-includes/bookmark.php - Jacob Santos
#5521 - /wp-includes/bookmark-template.php - Jacob Santos
#5511 - /wp-includes/cache.php - Jacob Santos
#5526 - /wp-includes/canonical.php - Jacob Santos
#5528 - /wp-includes/comment-template.php - Jacob Santos (help from Peter Walker #2648)
#5510 - /wp-includes/compat.php - Jacob Santos
#5527 - /wp-includes/default-filters.php - Jacob Santos
#5527 - /wp-includes/feed-rss2-comments.php - Jacob Santos
#5527 - /wp-includes/feed-rss2.php - Jacob Santos
#5527 - /wp-includes/feed-rdf.php - Jacob Santos
#5527 - /wp-includes/feed-atom-comments.php - Jacob Santos
#5527 - /wp-includes/feed-rss.php - Jacob Santos
#5527 - /wp-includes/feed-atom.php - Jacob Santos
#5641 - /wp-includes/kses.php - Jacob Santos
#5590 - /wp-includes/l10n.php - Jacob Santos
#5621 - /wp-includes/locale.php - Jacob Santos
#5509 - /wp-includes/pluggable.php – 由 Jacob Santos在Robert Deaton來(lái)自#2477的補(bǔ)丁的基礎(chǔ)上更新
#3852 - /wp-includes/plugin.php - Martin Sturm 和清除 by Jacob Santos (#5225)
#4383 - /wp-includes/registration.php - Robin Adrianse 和清除 by Jacob Santos
#5572 - /wp-includes/registration-functions.php - Jacob Santos
#4742 - /wp-includes/taxonomy.php - Jacob Santos
#5513 - /wp-includes/template-loader.php - Jacob Santos
#5233 - /wp-includes/update.php - Jacob Santos
#5572 - /wp-includes/vars.php - Jacob Santos
#5572 - /wp-includes/version.php - Jacob Santos
#2474 - /wp-includes/wpdb.php - Robert Deaton

未完成的文件[ ]

如果你想通過(guò)文件或者函數(shù)進(jìn)行資料編寫(xiě)，那么每個(gè)文件都應(yīng)該有個(gè)標(biāo)簽，作為工作的一部分，做完這個(gè)之后再添加到列表中。這些文件已經(jīng)開(kāi)始并且完成后可以使用一些幫助。

#5632 - /wp-includes/capabilities.php – 由 Jacob Santos開(kāi)始
#5633 - /wp-includes/category.php -由 Jacob Santos開(kāi)始
#5634 - /wp-includes/category-template.php -由 Jacob Santos開(kāi)始
#5635 - /wp-includes/classes.php -由 Jacob Santos開(kāi)始
#5637 - /wp-includes/cron.php -由 Jacob Santos開(kāi)始
#5578 - /wp-includes/comment.php – 在Peter Walker的來(lái)自#2648的補(bǔ)丁的基礎(chǔ)上由Jacob Santos更新
#5636 - /wp-includes/feed.php -由 Jacob Santos開(kāi)始
#5638 - /wp-includes/formatting.php -由 Jacob Santos開(kāi)始
#5639 - /wp-includes/functions.php -由 Jacob Santos開(kāi)始
#5640 - /wp-includes/general-template.php -由 Jacob Santos開(kāi)始
#5642 - /wp-includes/link-template.php -由 Jacob Santos開(kāi)始
#3982 - /wp-includes/post.php – 由Scott Merrill開(kāi)始, Jacob Santos在#2473的部分基礎(chǔ)上更新
#0000 - /wp-includes/post-template.php – 由你開(kāi)始
#0000 - /wp-includes/query.php - 由你開(kāi)始
#0000 - /wp-includes/script-loader.php -由你開(kāi)始
#0000 - /wp-includes/theme.php -由你開(kāi)始
#5512 - /wp-includes/user.php – 由Jacob Santos開(kāi)始
#0000 - /wp-includes/widgets.php -由你開(kāi)始

這個(gè)票已經(jīng)過(guò)期因?yàn)閍dmin-functions.php 不再使用并且在2.5+版本失效了. 文獻(xiàn)資料對(duì)于轉(zhuǎn)移到wp-admin/includes/*.* 文件夾下的函數(shù)仍然好用

#3970 - /wp-admin/admin-functions.php – 由 Sabin Iacob開(kāi)始