编辑“WordPress内嵌文档”

<span style="border:1px solid #000; text-align:center; float:right; padding:6px;"><strong>导航:</strong> [[WordPress协助开发须知|上一页]] | {{Template:WordPress导航}}</span>
<div style="clear:both;"></div>

本页面将成为给WordPress核心代码添加内嵌文档以帮助开发和改进WordPress的起点，同时它也帮会助他人了解[[PHP]]和WordPress。

本页面及其子页面都是为了发展内嵌文档的标准编写方法和格式，同时也是为了避免重复工作。理想情况下，内嵌文档应该尽量和[http://pear.php.net/manual/en/standards.sample.php PEAR样本]保持一致。

==需添加内嵌文档的代码==
全局文档为阅读源代码的 phpDocumentor和其它程序提供了如何使用全局变量的信息。由于核心开发人员可能并不接受补丁，因此这类信息并不是必须具备的，而且多数情况下也是不必要的。

函数和类方法通常要放在一定的文本环境中才有意义，而文档就是用来提供这个文本环境的，但内嵌文档不应当提供极端例子，除非在codex信息不能及时获得的小行代码中。

WordPress中使用的多数类都是单件（所有函数都包含在一个类中），但是它们经常要求手动初始化属性。很多情况下，何时在类中使用方法并不明了。

新添加的类及一些外部类库常使用多个类来形成函数库，这就创建了更多需要学习的新类（，因为基类（即开发人员使用的用来从其它类中提供函数的类）并不明确。这时，给中类层次库的类添加文档可使类功能更加清晰。

为了使类文档完整，应给类的属性添加文档。类的PHPdoc标签可以在其主网站找到，以下也有示例：

==PHPdoc标签==
PHPDoc标签和其它编辑程序一起用来显示代码文档。由于这些文档说明了代码的用途及使用位置，因此它对开发人员非常实用。

使用PHPdoc块时通常要包括WordPress的@since（即使当时并不了解这个信息）和@package信息，但外部库除外。

 /**   
 * ... Description(s) here   *   
 * @package WordPress   
 * @since 2.1 or { {@internal Unknown}}}   *   
 * ... More information if needed.   
 */  
除非编写 "TODO" 文档信息，否则在函数和方法块内部不会使用PHPdoc评论块。方法和函数内部的其它评论都不应该使用PHPdoc评论。

 /**   * @todo ... Description    */  
更多情况下会使用以下形式：
 /** @todo ... Description */

==映射Includes 和 Requires==
Includes和Requires的文档可用来说明所含文件的重要性，位置及和当前文件的关系。

虽然WordPress核心文件并不需要这些文档，但插件却可能需要文档说明，尤其是当插件代码被分成多个逻辑文件时。

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

==文件文档==
使用PHPdoc评论块的文件文档可用来概括文件所含内容。这样，用户无效逐个查看文件就能了解文件内容，大大减少了查阅时间。

有些 PHPdoc标签也可应用到phpDocumentor网站的所有其它PHPdoc评论块。

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

===全局PHPdoc评论块===
通常，为函数@uses 普遍使用的全局变量（globals）提供内嵌文档是非常有用的。

最好开篇就描述代码文档，因为这对程序员更有帮助。其它信息也可能比较重要，比如@since，但是@global标签只适用于phpDocumentator网站。

 /**   * ... Description    * @since   * @global    type    $varname   */  
===函数PHPdoc===
WordPress函数PHPdoc类型描述文档可短可长（如果合适的话）。

简短的描述不应再提及函数名称，而应直接概括函数的功能。要注意的是函数名称和功能可能并不吻合（名称和描述文字可能改变，但功能却不会变）。

但函数简短的文档描述内容也要完整。在某些情况下，也可注明简短描述缺失，如：

 /**   * Short Description  大多数函数都使用较长描述来详细说明简短描述的含义。多数情况下，摘要（summary）只是作为较长描述的引子。

有时，函数非常短，只用摘要就能描述函数的所有功能。这可由内嵌文档撰写者自主判断，但是通常情况下应该在PHPdoc块中应编写较长的注释。

 /**   * Short Description   *    * Long Description   *   */  
如果函数没有包括参数或返回文档来说明文档注释缺失，这也是可以接受的。但这只有在为多个函数编写内嵌文档时才能使用，而且应该留下一个说明（note）以示你是有意暂时没有添加文档描述，以待他人或你自己以后编写。

 /**   * { {@internal Missing Short Description}}}   *   * { {@internal Missing Long Description}}}   *   */  
另外，还可使用其它标签来提醒自己或告诉他人你并非有意不写内嵌文档。其它情况下，如果内嵌文档为空，通常认为他们有意留空，或认为没有必须添加注释，因为他人可以理解这个函数。如果在别处可以得知函数功能，那么内嵌文档也就没有存在的意义了。例如，如果全局变量已有内嵌文档了，@uses 标签无需再添加注释了。

 * @uses function_name() { {@internal Missing Description}}}对程序员和phpDocumentor 网站较为重要的其它信息：

 /**   * Short Description   *    
 * Long Description   *   
 * @package WordPress   
 * @since version   *   
 * @param    type    $varname    Description   
 * @return   type                Description   
 */  
@since 只和版本号连用，如 "2.1", 或 "2.3.1"，而且不使用其它字符串。@package信息用来给程序员和phpDocumentor 提供函数的应用信息，因此， 版本号码属于
@since。

为统一起见，如果可使用参数，每个函数的应该备注参数。如果函数使用了"return"，那么"return"标签就应该用来注释这个函数。如果没有使用"return"，就尽量不要
包括这个标签，因为如果存在，读者就会期望看到"return"这个关键词。

不要使用已过时的函数，而应标注版本的@deprecated标签和替代函数说明，还应包括@uses标签和函数名称。

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

===类PHPdoc===
WordPress类使用的 类PHPdoc 标签文档被有意排除。其中的一个注释（note）已注明类定义，类属性（变量）和类方法（函数）都需添加内嵌文档以使其完整。

使用的所有标签都应以[http://pear.php.net/manual/en/standards.sample.php PEAR样本]为参考。

==插件 @Package 标签==
插件作者在插件中禁止使用@package WordPress，因为这个包名称可以是任何已知事物的名称（包括插件）。

==内嵌文档撰稿者==
排名部分先后：

#Jacob Santos 
#Robin Adrianse 
#Scott Houston 
#Peter Westwood 
#Robert Deaton 
#Peter Walker 
#Martin Sturm 
#Sabin Iacob 

==拥有内嵌文档的文件==
WordPress中的当前文件列表，请查看WordPress文件介绍。

===外部库文件===
第三方库应该拥有文件级文档，但它们并不由WordPress文档团队维护。以下的第三方文件就拥有文件级文档。

以下是WordPress 2.5(1/10/2008)的外部文件列表，它们位于wp-includes目录下。截止到2008年5月25日，所有的外部库文件都已完成。

*atomlib.php 
*class-IXR.php 
*class-phpass.php 
*class-phpmailer.php 
*class-pop3.php 
*class-smtp.php 
*class-snoopy.php 
*gettext.php 
*streams.php 
*rss.php 
*rss-functions.php (已过时) 
==WordPress基目录文件==
WordPress基目录中的文件如有内嵌文档，这些文档就会在PHPXref 网站上显示。所有的基目录文件都已完成内嵌文档注释工作。

===WordPress WP-Includes文件===
这些文件都包括了完整的PHPdoc样式的文档和WordPress Trac   ticket编号。在WordPress发展过程中，新添加的函数并没有内嵌文档，这就致使这些文件并不完整。但WordPress2.7中wp-includes下的所有文件都已注释文档。

如果发现有的函数没有添加内嵌文档，请给其添加文档并提交补丁。所有的内嵌文档都有改进空间，因此，如发现有误或有待改进之处，请提交文档补丁。

*[http://trac.wordpress.org/ticket/4393 #4393] -   author-template.php 
*[http://trac.wordpress.org/ticket/5523 #5523] -   bookmark.php 
*[http://trac.wordpress.org/ticket/5521 #5521] -   bookmark-template.php 
*[http://trac.wordpress.org/ticket/5511 #5511] - cache.php 
*[http://trac.wordpress.org/ticket/5526 #5526] -   canonical.php 
*[http://trac.wordpress.org/ticket/5632 #5632] -   capabilities.php 
*[http://trac.wordpress.org/ticket/5633 #5633] -   category.php 
*[http://trac.wordpress.org/ticket/5634 #5634] -   category-template.php 
*[http://trac.wordpress.org/ticket/5635 #5635] -   classes.php 
*[http://trac.wordpress.org/ticket/5578 #5578] -   comment.php 
*[http://trac.wordpress.org/ticket/5528 #5528] -   comment-template.php 
*[http://trac.wordpress.org/ticket/5510 #5510] -   compat.php 
*[http://trac.wordpress.org/ticket/5637 #5637] - cron.php 
*[http://trac.wordpress.org/ticket/5527 #5527] -   default-filters.php 
*[http://trac.wordpress.org/ticket/5636 #5636] - feed.php 
*[http://trac.wordpress.org/ticket/5527 #5527] -   feed-atom.php 
*[http://trac.wordpress.org/ticket/5527 #5527] -   feed-rdf.php 
*[http://trac.wordpress.org/ticket/5527 #5527] -   feed-rss.php 
*[http://trac.wordpress.org/ticket/5527 #5527] -   feed-atom-comments.php 
*[http://trac.wordpress.org/ticket/5527 #5527] -   feed-rss2-comments.php 
*[http://trac.wordpress.org/ticket/5527 #5527] -   feed-rss2.php 
*[http://trac.wordpress.org/ticket/5638 #5638] -   formatting.php 
*[http://trac.wordpress.org/ticket/5639 #5639] -   functions.php 
*[http://trac.wordpress.org/ticket/5640 #5640] -   general-template.php 
*[http://trac.wordpress.org/ticket/5641 #5641] - kses.php 
*[http://trac.wordpress.org/ticket/5590 #5590] - l10n.php 
*[http://trac.wordpress.org/ticket/5642 #5642] -   link-template.php 
*[http://trac.wordpress.org/ticket/5621 #5621] -   locale.php 
*[http://trac.wordpress.org/ticket/7658 #7658] - media.php 
*[http://trac.wordpress.org/ticket/5509 #5509] -   pluggable.php 
*[http://trac.wordpress.org/ticket/5225 #5225] -   plugin.php 
*[http://trac.wordpress.org/ticket/7538 #7538] - post.php 
*[http://trac.wordpress.org/ticket/7659 #7659] -   post-template.php 
*[http://trac.wordpress.org/ticket/7663 #7663] - query.php 
*[http://trac.wordpress.org/ticket/4383 #4383] -   registration.php 
*[http://trac.wordpress.org/ticket/5572 #5572] -   registration-functions.php 
*[http://trac.wordpress.org/ticket/7660 #7660] -   rewrite.php 
*[http://trac.wordpress.org/ticket/7649 #7649] -   script-loader.php 
*[http://trac.wordpress.org/ticket/7184 #7184] -   shortcodes.php 
*[http://trac.wordpress.org/ticket/4742 #4742] -   taxonomy.php 
*[http://trac.wordpress.org/ticket/5513 #5513] -   template-loader.php 
*[http://trac.wordpress.org/ticket/7657 #7657] - theme.php 
*[http://trac.wordpress.org/ticket/5233 #5233] -   update.php 
*[http://trac.wordpress.org/ticket/5512 #5512] - user.php 
*[http://trac.wordpress.org/ticket/5572 #5572] - vars.php 
*[http://trac.wordpress.org/ticket/5572 #5572] -   version.php 
*[http://trac.wordpress.org/ticket/7661 #7661] -   widgets.php 
*[http://trac.wordpress.org/ticket/2474 #2474] - wpdb.php 
*[http://trac.wordpress.org/ticket/7662 #7662] -   wp-diff.php 

===WordPress WP-Admin文件===
wp-admin/中的文件是文件级文档，且其中的类也有内嵌文档。由于没有必要注释，因此其中的文件完并不完整。它还包括了wp-admin/includes/admin.php文件（因为其中并没有函数，只是包含了其它的函数文件。）

WordPress WP-Admin Includes FilesWordPress WP-Admin Includes文件

*[http://trac.wordpress.org/ticket/3970 Ticket   #3970]已过期，因为admin-functions.php已不再是函数文件，它对2.5以上版本均不适用。其中一些有用的函数已移至wp-admin/includes   目录下。

*[http://trac.wordpress.org/ticket/3970 Ticket   #3970]中的修补内容由Sabin Iacob撰写。

'''Complete（完整文件）:'''

*[http://trac.wordpress.org/ticket/7527 #7527] image.php 
*[http://trac.wordpress.org/ticket/7527 #7527] import.php 
*[http://trac.wordpress.org/ticket/7527 #7527] plugin-install.php 
*[http://trac.wordpress.org/ticket/7527 #7527] schema.php 
*[http://trac.wordpress.org/ticket/7527 #7527] update-core.php 

'''Incomplete（不完整文件）:'''
*[http://trac.wordpress.org/ticket/7527 #7527] bookmark.php (9 functions) 
*[http://trac.wordpress.org/ticket/7527 #7527] comment.php   (5 functions) 
*[http://trac.wordpress.org/ticket/7527 #7527] dashboard.php (13 functions) 
*[http://trac.wordpress.org/ticket/7527 #7527] export.php   (9 functions) 
*[http://trac.wordpress.org/ticket/7527 #7527] file.php   (17 functions) 
*[http://trac.wordpress.org/ticket/7527 #7527] media.php   (40 functions) 
*[http://trac.wordpress.org/ticket/7527 #7527] misc.php (9   functions) 
*[http://trac.wordpress.org/ticket/7527 #7527] plugin.php   (22 functions) 
*[http://trac.wordpress.org/ticket/7527 #7527] post.php   (26 functions) 
*[http://trac.wordpress.org/ticket/7527 #7527] taxonomy.php (10 functions) 
*[http://trac.wordpress.org/ticket/7527 #7527] template.php (37 functions, 1 class, 37 methods) 
*[http://trac.wordpress.org/ticket/7527 #7527] theme.php   (3 functions) 
*[http://trac.wordpress.org/ticket/7527 #7527] update.php   (6 functions) 
*[http://trac.wordpress.org/ticket/7527 #7527] upgrade.php   (36 functions) 
*[http://trac.wordpress.org/ticket/7527 #7527] user.php (9   functions, 9 methods, 1 class) 
*[http://trac.wordpress.org/ticket/7527 #7527] widgets.php   (5 functions)

==WP-Hackers的Discussions(讨论)历史==
WP-Hackers列表上包括许多关于添加内嵌文档的历史讨论。但最近的邮件列表中，WP黑客成员并没有提及这个页面。其实，只要给WordPress文件添加足够详尽的内嵌文档，WP-Hackers和其它邮件列表就没有必要进行讨论了。

*[http://comox.textdrive.com/pipermail/wp-hackers/2006-February/004921.html Inline Documentation] (February 2006) 
*[http://comox.textdrive.com/pipermail/wp-hackers/2006-February/004989.html PATCH Documentation] (February 2006) 
*[http://comox.textdrive.com/pipermail/wp-hackers/2007-October/015584.html Proposal for a function commenting convention] (October 2007) 
*[http://comox.textdrive.com/pipermail/wp-hackers/2008-May/020214.html Inline Documentation Effort Was a Failure] (May 2008)
==资源==
*[http://phpxref.com/xref/wordpress/nav.html.gz?index.html.gz English Version] 
*[http://www.phpdoc.org/ phpDocumentor] - Auto-documentation tool for php语言的自动 language (phpdoc.org) 
*[http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html phpDocumentor Tutorial] - 如何使用phpDocumentor (phpdoc.org) 
*[http://www.zend.com/store/products/zend-studio/ Zend Studio] - PHP开发环境 (商业产品) 
*At aptana.tv there is [http://www.aptana.tv/movies/aptana_scriptdoc_overview/ScriptDocOverview.html a video showing the power of proper inline documentation]. 其中包括一些使用的标签。

==相关条目==
*[[Drupal]] 
*[[OBLOG]] 
*[[X-Space]] 
*[[SaBlog-X]] 
*[[Bo-Blog]]

[[category:WordPress中文文档|G]]