内嵌文档

 

本页面将成为给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，因为这个包名称可以是任何已知事物的名称（包括插件）。

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. 其中包括一些使用的标签。

内嵌文档撰稿者

排名部分先后：

1. Jacob Santos
2. Robin Adrianse
3. Scott Houston
4. Peter Westwood
5. Robert Deaton
6. Peter Walker
7. Martin Sturm
8. 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下的所有文件都已注释文档。

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

1. #4393 – author-template.php
2. #5523 – bookmark.php
3. #5521 – bookmark-template.php
4. #5511 – cache.php
5. #5526 – canonical.php
6. #5632 – capabilities.php
7. #5633 – category.php
8. #5634 – category-template.php
9. #5635 – classes.php
10. #5578 – comment.php
11. #5528 – comment-template.php
12. #5510 – compat.php
13. #5637 – cron.php
14. #5527 – default-filters.php
15. #5636 – feed.php
16. #5527 – feed-atom.php
17. #5527 – feed-rdf.php
18. #5527 – feed-rss.php
19. #5527 – feed-atom-comments.php
20. #5527 – feed-rss2-comments.php
21. #5527 – feed-rss2.php
22. #5638 – formatting.php
23. #5639 – functions.php
24. #5640 – general-template.php
25. #5641 – kses.php
26. #5590 – l10n.php
27. #5642 – link-template.php
28. #5621 – locale.php
29. #7658 – media.php
30. #5509 – pluggable.php
31. #5225 – plugin.php
32. #7538 – post.php
33. #7659 – post-template.php
34. #7663 – query.php
35. #4383 – registration.php
36. #5572 – registration-functions.php
37. #7660 – rewrite.php
38. #7649 – script-loader.php
39. #7184 – shortcodes.php
40. #4742 – taxonomy.php
41. #5513 – template-loader.php
42. #7657 – theme.php
43. #5233 – update.php
44. #5512 – user.php
45. #5572 – vars.php
46. #5572 – version.php
47. #7661 – widgets.php
48. #2474 – wpdb.php
49. #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（完整文件）:

1. #7527 image.php
2. #7527 import.php
3. #7527 plugin-install.php
4. #7527 schema.php
5. #7527 update-core.php

Incomplete（不完整文件）:

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

 

分类：中文手册