Inline Documentation

来自WordPress中文文档
跳转至: 导航搜索

This page is the start of the effort to add inline documentation to the WordPress core code to aid in future development, improvements and changes, as well as to assist others when learning about PHP and WordPress.

Use of this page and subsequent child pages is meant for developing standard methodologies and formats, as well as to ensure that there is no duplication of effort. In the best case, inline documentation should appear as close to this PEAR sample.

What Should be Documented

Documenting globals gives information for phpDocumentor and others reading the source code on how the global is used. It isn't required and in most cases not necessary, since the core developers may not accept the patches.

Functions and class methods are often difficult to be used without context. Documentation can offer context, but inline documentation should not be used for giving extreme examples, except for small lines of code where codex information is not immediately available.

Most of the classes used in WordPress are Singletons (the entire functionality is contained in a single class), but often require initializing of properties manually. Often the question of when to use a method in a class is not clear in most situations.

Newer class additions and some external libraries use multiple classes to form a library for functionality. This creates a higher learning curve as the base class (the class the developer uses that provides the functionality from all of the rest of the classes) is not clear. Adding documentation on where the class falls in the class library hierarchy provides more clarity.

The properties of classes need to be documented for class documentation completeness. The PHPdoc tags for those can be found at the main site and an example can be found below.

PHPdoc Tags

PHPDoc tags work with some editors to display more information about a piece of code. It is useful to developers using those editors to understand what the purpose and where they would use it in their code.

The convention for allowing PHPdoc blocks is to have @since information (even if not available at the time) and @package information, which should always be "WordPress" unless it is an external library.

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

You will not use PHPdoc comment blocks inside function and method blocks, except to document "TODO" information. All other comments inside methods and functions should not use PHPdoc comments.

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

Or the second form can be used is most cases.

/** @todo ... Description */

Mapping Includes and Requires

Documenting includes and requires can be useful to explain what relationship the included file has to the current file and why it is needed and what can be found in it.

Not necessary for WordPress core files, but might be useful for your own plugins, if you split the code into logical files.

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

File Documentation

File documentation using PHPdoc comment blocks can be used to give an overview on what the file holds and what can be found in the file. Used to its full advantage may prevent someone from exploring the file too deeply and wasting their time.

Some PHPdoc tags can be applied globally to every other PHPdoc comment block for phpDocumentor sites.

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

Global PHPdoc Comment Block

Often it is useful to document globals that are commonly used for the function @uses reference.

It is better to have the description first as it is what the coder needs. The rest of the information might be important, @since for example, but @global tag is only useful for phpDocumentator sites.

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

Function PHPdoc

The convention for WordPress function PHPdoc types includes the short description and long description (if applicable).

The short description should not restate what the function name is, but look deeper in to what the function does (the code) and summarize that. The function name might say one thing, but actually do something completely different (the specs changed, but the usage did not).

The short description is required for the documentation of the function to be considered complete. A note may be left in certain circumstances, see below, that lets others know that the short description is missing.

/**
 * Short Description

Long descriptions should be included in most functions to give clarity to what the short description means. In most cases, the summary should only serve as a reminder to what the coder read in the long description.

In rare cases, the function is so short that the summary can be used to describe the full extent of the function's purpose. It is up to the documentation author's judgment, but as a rule always try to include the long descriptions in the PHPdoc block.

/**
 * Short Description
 * 
 * Long Description
 *
 */

It is acceptable if the function does not have parameter or return documentation to leave a note that the short and long descriptions are missing. This should only be used when you are writing documentation for a multiple functions are only leaving a note that you intentionally left that area blank for someone else or for yourself to complete later.

/**
 * {{@internal Missing Short Description}}}
 *
 * {{@internal Missing Long Description}}}
 *
 */

For other tags to remind yourself or others that you did not mean for the tag to be blank in that area. Other times, it should be assumed that if someone left something blank, that they meant to do so, or didn't think the description was required for others to understand the function. The information might not serve any purpose if it is available elsewhere. For example in the @uses tag for globals, if the global variable was already documented.

 * @uses function_name() {{@internal Missing Description}}}

After the short and long description, other information is important to the coder and phpDocumentor sites.

/**
 * Short Description
 * 
 * Long Description
 *
 * @since version
 *
 * @param    type    $varname    Description
 * @return   type                Description
 */

The convention for @since is to use just the version number, "2.1", or "2.3.1" and leave off any other strings. The @package information gives coders and phpDocumentor which application the function and therefore the @since application the version number belongs to.

For consistency, if parameters are available, they must always be documented for every function. If the "return" keyword is used anywhere in the function, then the @return tag should be used to document that possible case. If it does not exist, then it is best to not include the tag, because if it exists, the reader might expect it to have the "return" keyword.

If the function is deprecated, should not be used any longer, then the @deprecated tag along with the version and description of what to use instead should be given. Also include the @uses tag with the function name.

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

Class PHPdoc tags

The information on class PHPdoc tags to use in WordPress classes is intentionally left out. One note is that the class definition, the class properties (variables), and class methods (functions) all need to have documentation to be complete.

The PEAR sample should be referenced for the tags to use for each.

@author Tag

It is WordPress' policy not to use the @author Tag except in the case of maintaining it in external libraries. We don't want to imply any sort of "ownership" over code that might discourage contribution.

Plugin @Package Tag

Plugin authors must not use the @package WordPress in their plugins. The package name can be anything known to be unique and can be the plugin name.

Past WP-Hackers Discussions

The WP-Hackers list has a number of past discussions on adding inline documentation. In recent cases, this page was not referenced or found during the discussion. By documenting WordPress files, the discussions on WP-Hackers and elsewhere can be brought to a close if enough effort is put forth to do the work to document the files.

Resources

Inline Documentation Effort Contributors

Listed in no specific order.

  1. Jacob Santos
  2. Robin Adrianse
  3. Scott Houston
  4. Peter Westwood
  5. Robert Deaton
  6. Peter Walker
  7. Martin Sturm
  8. Sabin Iacob

Files with Inline Documentation

For a list of current files in WordPress, see WordPress Files.

External Library Files

Third party libraries should have file level documentation, but should not be part of the WordPress documentation effort. The following third party files have file level documentation.

Below is the list of external files in WordPress 2.5 (1/10/2008). These files are in the wp-includes directory. As of May 25, 2008 the external library files are all completed.

  • 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 (deprecated)

WordPress Base Directory Files

These files exist in the base directory of WordPress, which if they have file based documentation will show up in PHPXref sites on the side. All base directory files are completed.

Incomplete Documentation

  • wp-activate.php (wpmu addition)
  • wp-login.php (wp_shake_js()).
  • wp-signup.php (wpmu addition)
  • xmlrpc.php (new methods: serve_request(), add_enclosure_if_new(), )

WordPress WP-Includes Files

These files have complete PHPdoc style documentation with the WordPress Trac ticket number. During the development of WordPress, new functions will be added that won't have inline documentation causing these files to be incomplete again. Since WordPress 2.7, all files within wp-includes directory are complete.

If you find a function that isn't documented, please document that function and submit a patch to complete it. All inline documentation should be considered a work in progress, so if you find mistakes or improvements, please also submit patches for those too.

  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

Incomplete Files

Since WordPress 2.9, the inline documentation has both improved in wp-admin sections and decreased in wp-includes. With 3.0, it will be high time to bring wp-includes back up to complete status.

  • functions.php ( 2 functions ).
  • l10n.php
  • media.php
  • ms-blogs.php
  • ms-default-filters.php
  • ms-files.php
  • ms-functions.php
  • post.php
  • script-loader.php
  • update.php
  • user.php (improve phpdoc).
  • widgets.php (new class, properties, and methods).
  • wp-db.php (1 method)

WordPress WP-Admin Files

The files in wp-admin/ has file level documentation the classes have been documented. There isn't a complete list of files, because it would be redundant to have it. The wp-admin/includes/admin.php file is included here because it doesn't have any functions, just includes other files that do.

WordPress WP-Admin Includes Files

Ticket #3970 is outdated because admin-functions.php is no longer used for functions and is deprecated in 2.5+. The documentation is still good for the functions that were moved to the wp-admin/includes directory. The patch in Ticket #3970 was written by 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)