WordPress内嵌文档

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

本页面及其子页面都是为了发展内嵌文档的标准编写方法和格式，同时也是为了避免重复工作。理想情况下，内嵌文档应该尽量和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）已注明类定义，类属性（变量）和类方法（函数）都需添加内嵌文档以使其完整。

使用的所有标签都应以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下的所有文件都已注释文档。

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

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

WordPress WP-Admin文件[ ]

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

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

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

Ticket #3970中的修补内容由Sabin Iacob撰写。

Complete（完整文件）:

#7527 image.php
#7527 import.php
#7527 plugin-install.php
#7527 schema.php
#7527 update-core.php

Incomplete（不完整文件）:

#7527 bookmark.php (9 functions)
#7527 comment.php (5 functions)
#7527 dashboard.php (13 functions)
#7527 export.php (9 functions)
#7527 file.php (17 functions)
#7527 media.php (40 functions)
#7527 misc.php (9 functions)
#7527 plugin.php (22 functions)
#7527 post.php (26 functions)
#7527 taxonomy.php (10 functions)
#7527 template.php (37 functions, 1 class, 37 methods)
#7527 theme.php (3 functions)
#7527 update.php (6 functions)
#7527 upgrade.php (36 functions)
#7527 user.php (9 functions, 9 methods, 1 class)
#7527 widgets.php (5 functions)

WP-Hackers的Discussions(讨论)历史[ ]

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

Inline Documentation (February 2006)
PATCH Documentation (February 2006)
Proposal for a function commenting convention (October 2007)
Inline Documentation Effort Was a Failure (May 2008)

资源[ ]

English Version
phpDocumentor - Auto-documentation tool for php语言的自动 language (phpdoc.org)
phpDocumentor Tutorial - 如何使用phpDocumentor (phpdoc.org)
Zend Studio - PHP开发环境 (商业产品)
At aptana.tv there is a video showing the power of proper inline documentation. 其中包括一些使用的标签。

WIKI使用导航

站长百科导航

站长专题