WordPress: Inline Documentation：修訂間差異

2008年5月14日 (三) 16:14的版本

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

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

什么應(yīng)該備有資料文獻

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

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

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

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

PHPdoc標(biāo)簽

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

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

/**
 * ... 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)有的文件有什么關(guān)系，以及為什么需要它和在它里面能找到些什么是很有用的。

對于WordPress核心文件來說并不是必需的，但是如果你吧代碼分成邏輯文件的話，可能對你的插件很有用。

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

文件資料

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

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

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

全局PHPdoc注釋模塊

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

先得到描述信息，因為那是編碼器所需要的。其他的信息也許也重要，用@since舉例，@ global標(biāo)簽只對phpDocumentator站點有用。

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

函數(shù) PHPdoc

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

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

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

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

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

<

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

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

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

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

在短和長描述后，別的信息對于編碼器和phpDocumentor 站點也是很重要的。

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

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

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

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

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

類PHPdoc 標(biāo)簽

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

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

過去的 WP-Hackers 討論

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

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

資源

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

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

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

外部庫文件

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

所有的外部庫文件都完成了

/wp-includes/atomlib.php
/wp-includes/class-IXR.php
/wp-includes/class-phpass.php
/wp-includes/class-phpmailer.php (不需要文件級別的資料，因為它有類級別的資料)
/wp-includes/class-pop3.php
/wp-includes/class-smtp.php (不需要文件級別的資料，因為它有類級別的資料)
/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 號碼。

#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來自#2477的補丁的基礎(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

未完成的文件

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

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

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

#3970 - /wp-admin/admin-functions.php – 由 Sabin Iacob開始