内嵌文档

0条评论

 

本页面将成为给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和其它邮件列表就没有必要进行讨论了。

资源

内嵌文档撰稿者

排名部分先后:

  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)