Codex tools: Log in
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.
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 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 */
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 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 */
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 */
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 */
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.
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 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.
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.
Listed in no specific order.
For a list of current files in WordPress, see WordPress 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.
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.
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.
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.
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.
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:
Incomplete:
