WordPress:Inline Documentation

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 allow 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 must include the function name with only the parenthesize '()'. 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.

/**
 * function_name() - 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.

/**
 * function_name() - 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.

/**
 * function_name() - {{@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.

/**
 * function_name() - Short Description
 * 
 * Long Description
 *
 * @package WordPress
 * @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.

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.

• Inline Documentation (February 2006)
• PATCH Documentation (February 2006)
• Proposal for a function commenting convention (October 2007)

Resources

• English Version
• phpDocumentor - Auto-documentation tool for php language (phpdoc.org)
• phpDocumentor Tutorial - How to use phpDocumentor (phpdoc.org)
• Zend Studio - PHP Development Environment (commercial product)
• At aptana.tv there is a video showing the power of proper inline documentation. Some tags are really helpful as you can see there.

Files with Inline Documentation

For a list of current files in WordPress, see WordPress: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).

All external library files are completed

• /wp-includes/atomlib.php
• /wp-includes/class-IXR.php
• /wp-includes/class-phpass.php
• /wp-includes/class-phpmailer.php (does not need file level documentation because it has class level documentation)
• /wp-includes/class-pop3.php
• /wp-includes/class-smtp.php (does not need file level documentation because it has class level documentation)
• /wp-includes/class-snoopy.php
• /wp-includes/gettext.php
• /wp-includes/streams.php
• /wp-includes/rss.php
• /wp-includes/rss-functions.php (deprecated)

WordPress Finished Files

These files have complete PHPdoc style documentation. Listed are the documentation writer, along with the WordPress Trac ticket number.

1. #5211 - /wp-settings.php - Jacob Santos (Use as an example for other files)
2. #4393 - /wp-includes/author-template.php - Robin Adrianse and cleanup by Jacob Santos
3. #5523 - /wp-includes/bookmark.php - Jacob Santos
4. #5521 - /wp-includes/bookmark-template.php - Jacob Santos
5. #5511 - /wp-includes/cache.php - Jacob Santos
6. #5526 - /wp-includes/canonical.php - Jacob Santos
7. #5528 - /wp-includes/comment-template.php - Jacob Santos (help from Peter Walker #2648)
8. #5510 - /wp-includes/compat.php - Jacob Santos
9. #5527 - /wp-includes/default-filters.php - Jacob Santos
10. #5527 - /wp-includes/feed-rss2-comments.php - Jacob Santos
11. #5527 - /wp-includes/feed-rss2.php - Jacob Santos
12. #5527 - /wp-includes/feed-rdf.php - Jacob Santos
13. #5527 - /wp-includes/feed-atom-comments.php - Jacob Santos
14. #5527 - /wp-includes/feed-rss.php - Jacob Santos
15. #5527 - /wp-includes/feed-atom.php - Jacob Santos
16. #5641 - /wp-includes/kses.php - Jacob Santos
17. #5590 - /wp-includes/l10n.php - Jacob Santos
18. #5621 - /wp-includes/locale.php - Jacob Santos
19. #5509 - /wp-includes/pluggable.php - Updated by Jacob Santos based on Robert Deaton's patch from #2477
20. #3852 - /wp-includes/plugin.php - Martin Sturm and cleanup by Jacob Santos (#5225)
21. #4383 - /wp-includes/registration.php - Robin Adrianse and cleanup by Jacob Santos
22. #5572 - /wp-includes/registration-functions.php - Jacob Santos
23. #4742 - /wp-includes/taxonomy.php - Jacob Santos
24. #5513 - /wp-includes/template-loader.php - Jacob Santos
25. #5233 - /wp-includes/update.php - Jacob Santos
26. #5572 - /wp-includes/vars.php - Jacob Santos
27. #5572 - /wp-includes/version.php - Jacob Santos
28. #2474 - /wp-includes/wpdb.php - Robert Deaton

Incomplete Files

Every file should be labeled as a work in progress and if you want to adopt a file or function for documentation, then do so and add it to this list. These files however have already been started and could use some help with completion.

1. #5632 - /wp-includes/capabilities.php - Started by Jacob Santos
2. #5633 - /wp-includes/category.php - Started by Jacob Santos
3. #5634 - /wp-includes/category-template.php - Started by Jacob Santos
4. #5635 - /wp-includes/classes.php - Started by Jacob Santos
5. #5637 - /wp-includes/cron.php - Started by Jacob Santos
6. #5578 - /wp-includes/comment.php - Updated by Jacob Santos based on Peter Walker's patch from #2648
7. #5636 - /wp-includes/feed.php - Started by Jacob Santos
8. #5638 - /wp-includes/formatting.php - Started by Jacob Santos
9. #5639 - /wp-includes/functions.php - Started by Jacob Santos
10. #5640 - /wp-includes/general-template.php - Started by Jacob Santos
11. #5642 - /wp-includes/link-template.php - Started by Jacob Santos
12. #3982 - /wp-includes/post.php - Started by Scott Merrill, updated by Jacob Santos and based in part off of #2473.
13. #0000 - /wp-includes/post-template.php - Started by You
14. #0000 - /wp-includes/query.php - Started by You
15. #0000 - /wp-includes/script-loader.php - Started by You
16. #0000 - /wp-includes/theme.php - Started by You
17. #5512 - /wp-includes/user.php - Started by Jacob Santos
18. #0000 - /wp-includes/widgets.php - Started by You

This ticket 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/*.* folder.

• #3970 - /wp-admin/admin-functions.php - Started by Sabin Iacob