編輯“WordPress:Inline Documentation”

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

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

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

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

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

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

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

== PHPdoc標(biāo)簽==

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

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

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


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

<pre>
/**
 * @todo ... Description
 */
</pre>

Or the second form can be used is most cases.
<pre>/** @todo ... Description */</pre>

== 映射Includes 和Requires ==

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

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

<pre>
/** 
 * This file holds all of the users
 * custom information
 */
require ABSPATH.'/wp-config.php';
</pre>
== 文件資料 ==

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

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

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


== 全局PHPdoc注釋模塊 ==

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

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

<pre>
/**
 * ... Description 
 * @since
 * @global    type    $varname
 */
</pre>

== 函數(shù) PHPdoc ==

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

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



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


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

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

<</pre>

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

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


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

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

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

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

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

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

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

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

== 類PHPdoc 標(biāo)簽 ==

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

[http://pear.php.net/manual/en/standards.sample.php PEAR 樣本]應(yīng)該用來作為這些標(biāo)簽的使用的參考。

==過去的 WP-Hackers 討論==

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

*[http://comox.textdrive.com/pipermail/wp-hackers/2006-February/004921.html 內(nèi)嵌文檔] (February 2006)
*[http://comox.textdrive.com/pipermail/wp-hackers/2006-February/004989.html PATCH 文檔] (February 2006)
*[http://comox.textdrive.com/pipermail/wp-hackers/2007-October/015584.html 函數(shù)注釋約定建議] (October 2007)

==資源==
* [http://phpxref.com/xref/wordpress/nav.html.gz?index.html.gz 英文版]
*[http://www.phpdoc.org/ phpDocumentor] –為php語言自動建立檔案的工具  (phpdoc.org)
*[http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html phpDocumentor 指南] – 如何使用 phpDocumentor (phpdoc.org)
*[http://www.zend.com/store/products/zend-studio/ Zend 工作室] - PHP 開發(fā)環(huán)境 (商業(yè)產(chǎn)品)
* 在 aptana.tv 有 [http://www.aptana.tv/movies/aptana_scriptdoc_overview/ScriptDocOverview.html 一個視頻展示出適當(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 (不需要文件級別的資料，因?yàn)樗蓄惣墑e的資料)
* /wp-includes/class-pop3.php
* /wp-includes/class-smtp.php (不需要文件級別的資料，因?yàn)樗蓄惣墑e的資料)
* /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 號碼。

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

===未完成的文件===

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

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

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

* [http://trac.wordpress.org/ticket/3970 #3970] - /wp-admin/admin-functions.php – 由 Sabin Iacob開始
本頁面是添加內(nèi)嵌文檔到WordPress核心代碼來幫助將來的發(fā)展，改進(jìn)和更新的起點(diǎn)，同樣也是在學(xué)習(xí)PHP 和 WordPress時幫助別人。

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