WordPress:Inline Documentation

本页面是添加内嵌文档到WordPress核心代码来帮助将来的发展，改进和更新的起点，同样也是在学习PHP 和 WordPress时帮助别人。

本页面以及后来的子页面意味这开发标准方法和格式，也是为了保证没有副作用。在最好的情况下，内嵌文档应该出现在靠近这个PEAR 样本的地方。

什么应该备有资料文献[ ]

备份phpDocumentor的资料文献，和其他关于global如何使用的阅读源代码。它不是必需的，而且在大多数时候都不是必需的，因为核心开发人员可能不能接受这个补丁。函数和类方法在没有上下文环境的时候很难使用。文件可以提供上下文，但是内嵌文档不应该用来给出极端的例子，除非在codex 信息不能立即获得的小行代码中。

多数WordPress中使用的类都是单独的(全部的功能包含在一个单独的类中), 但是通常要求手动初始化属性。大多数情况下什么时候在类中使用方法是不清楚的。

新的附加类和一些外部的库使用多种类来组成有某种功能的库。这创建了一个更高的学习曲线，因为基类(开发者用来提供从所有其他类获得其功能的类) 不清楚。给类所在的类库层次中添加文档会提供更高的清晰度。

为了类资料的完整性，类的属性需要备有资料文献。用于这功能的PHPdoc 标签可以在主页找到，例子可以在下面找到。

PHPdoc标签[ ]

PHPDoc 标签和一些编辑器一起显示更多有关于一段代码的信息。对开发者使用那些编辑器来了解目标是什么以及在他们的代码中能在什么地方使用是很有用的。

允许PHPdoc 模块的惯例是含有@since 信息(尽管目前不可用)和@package信息, 必须是"WordPress"，除非是一个外部库。

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

在函数和方法模块内不能使用PHPdoc注释模块，除非提供 "TODO" 信息。所有其他的方法和函数内不能使用PHPdoc注释。

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

Or the second form can be used is most cases.

/** @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参数的全局资料通常是有用的。

先得到描述信息，因为那是编码器所需要的。其他的信息也许也重要，用@since举例，@ global标签只对phpDocumentator站点有用。

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

函数 PHPdoc[ ]

WordPress 函数 PHPdoc类型包括短描述和长描述(如果适用的话).

短描述必须包括只带括号'()'的函数名字。短描述不应该重复说名函数名是什么，而应该深入一些描述这个函数是做什么的(代码)并作总结。函数名字可能表达了什么，但事实上做的却是完全不同的东西(规格改变了但是用法没有变)。

短描述要求完全考虑到这个函数的文献资料。在特殊情况下可能会留下记录，如下，让人知道短描述丢失了。

长描述应该包含在大多数的函数中，来清楚地给出短描述包含的意思。大多数情况下，摘要只是作为在长描述中编码器读取的提示。

极少情况下，函数非常的短，摘要就可以描述全部的函数目的范围了。这取决于文献资料作者的判断，但是作为一个规则，应该尝试吧长描述包括到PHPdoc 模块中去。

<

如果函数没有参数，或者返回资料留下短和长描述丢失的记录，这是可以接受的。这只能在你为一个多重函数写资料时，留下一个你专门为别人或者你自己留下空白以便将来完成的记录时，才可以使用。

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

对于其他提醒你或者你本不想留下空白的标签。其他时候，它应该被认为是有人故意留下空白，或者是不认为描述对于别人理解函数是必须的。信息可能并不服务于某种目的，如果在别的地方也可以找到的话。如，在使用@uses标签时，如果全局变量已经拥有资料时。

 * @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 信息给出了编码器和请求函数用的phpDocumentor，这样@since 就会请求属于它的版本号。

为了保持一致，如果参数可用，它们必须为每个函数建立资料文献。如果"return" 关键词在函数中的任何地方使用，那么@return标签应该被用来建立可能的资料。如果它不存在的话，最好就不要包含这个标签，因为如果它存在，读者可能希望它能有 "return" 这个关键词。

如果函数被反对，就不应该继续使用了，然后会给出@deprecated 标签连同版本和使用哪些作为替代的描述。同样包括带有函数名字的@uses标签。

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

类PHPdoc 标签[ ]

关于类PHPdoc标签的在WordPress类中使用的信息是故意删除的。注意类的定义，属性（变量），和类方法（函数）都需要建立文献资料。

PEAR 样本应该用来作为这些标签的使用的参考。

过去的 WP-Hackers 讨论[ ]

WP-Hackers列表有大量过去的关于添加内嵌文档的讨论。在最近的一些案例中，这个页面无法在讨论中引用或者被发现。通过给WordPress文件建立资料，关于WP-Hackers和别的东西的讨论可以结束了，如果足够的努力放到给这些文件建立档案文献的话。

内嵌文档 (February 2006)
PATCH 文档 (February 2006)
函数注释约定建议 (October 2007)

资源[ ]

英文版
phpDocumentor –为php语言自动建立档案的工具 (phpdoc.org)
phpDocumentor 指南 – 如何使用 phpDocumentor (phpdoc.org)
Zend 工作室 - PHP 开发环境 (商业产品)
在 aptana.tv 有一个视频展示出适当的内嵌文档的力量. 一些标签就如你在那看到的一样，非常有用。

拥有内嵌文档的文件[ ]

想得到一个WordPress中现有文件的列表，参见WordPress:WordPress 文件.

外部库文件[ ]

第三方的库应该有文件级别的资料，但是不应该成为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 完成的文件[ ]

这些文件已经完成了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的补丁的基础上更新
#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

未完成的文件[ ]

如果你想通过文件或者函数进行资料编写，那么每个文件都应该有个标签，作为工作的一部分，做完这个之后再添加到列表中。这些文件已经开始并且完成后可以使用一些帮助。

#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的补丁的基础上由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的部分基础上更新
#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 -由你开始

这个票已经过期因为admin-functions.php 不再使用并且在2.5+版本失效了. 文献资料对于转移到wp-admin/includes/*.* 文件夹下的函数仍然好用

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