Source Code Documentation Recommendations for PHP WordPress Plugins02.07.25

Source Code Documentation Recommendations for PHP WordPress Plugins

To create high-quality WordPress plugins, adhering to coding standards and providing thorough documentation is crucial. This ensures code readability, maintainability, and collaboration within the WordPress community. Here's a breakdown of source code documentation recommendations for PHP WordPress plugins, drawing from authoritative sources:
General Documentation Principles
File Headers

The primary goal of documentation is to explain what the code does, not necessarily why it exists. Summaries should be clear, concise, and written in the third-person singular.[2] For example, instead of "Display the date," use "Displays the last modified date."[2]

Every PHP file in a WordPress plugin should include a file header DocBlock. This DocBlock provides an overview of the file's purpose and includes essential information:
Functions and Class Methods

The summary should be a succinct description of the file's specific purpose. The description can provide more detailed overview information.[2]

/**
 * Summary (no period for file headers)
 *
 * Description. (use period)
 *
 * @link URL
 *
 * @package WordPress
 * @subpackage Component
 * @since x.x.x (when the file was introduced)
 */

Functions and class methods should be documented with a DocBlock preceding their definition. The DocBlock should include:

Summary: A brief, one-sentence explanation of the function's purpose, ending with a period.[2]
    Description: A more detailed explanation of the function's functionality. Use complete sentences and end with a period.[2]
    @since: The version of WordPress the function was introduced in. Use the 3-digit format (e.g., @since 3.9.0).[2]
    @see: References to related functions, methods, or classes.[2]
    @link: A URL providing more information.[2]
    @global: Lists PHP globals used within the function, with an optional description.[2]
    @param: Describes each parameter, including its type, name, and a description. Indicate if a parameter is optional and its default value.[2]
    @return: Describes the return type(s) and a description for each. @return void should be avoided outside of bundled themes and PHP compatibility shims.[2]

Classes

For parameters that are arrays, document the array values using a hash notation style, as demonstrated in the WordPress documentation.[2]

/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 *
 * @see Function/method/class relied on
 * @link URL
 * @global type $varname Description.
 * @global type $varname Description.
 *
 * @param type $var Description.
 * @param type $var Optional. Description. Default.
 * @return type Description.
 */

Class DocBlocks should be formatted as follows:

Summary: A brief, one-sentence explanation of the class's purpose, ending with a period.[2]
    Description: A more detailed description of the class's purpose, ending with a period.[2]
    @since: The version of WordPress the class was introduced in. Use the 3-digit format (e.g., @since 3.9.0).[2]

Class properties and constants should also be documented:
Class Members (Properties and Constants)

/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 *
 * @see Super_Class
 */

Summary: A brief description, ending with a period.[2]
    @since: The version of WordPress the member was introduced in. Use the 3-digit format (e.g., @since 3.9.0).[2]
    @var: Describes the property or constant's type and a description.[2]

Files included using require_once or include_once should be documented with a summary description DocBlock.[2]
Requires and Includes

/**
 * Summary.
 *
 * @since x.x.x
 * @var type $var Description.
 */

Action and filter hooks should be documented immediately before the do_action() or apply_filters() call. The DocBlock should include:
Hooks (Actions and Filters)

/**
 * Summary.
 */
require_once( ABSPATH . WPINC . '/filename.php' );

Summary: A brief, one-line explanation of the hook's purpose, ending with a period.[2]
    Description: A supplemental description, if needed.[2]
    @since: The version of WordPress the hook was introduced in. Use the 3-digit format (e.g., @since 3.9.0).[2]
    @param: Describes each parameter using a hash notation for array arguments.[2]

/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 *
 * @param type $var Description.
 * @param array $args {
 *  Short description about this hash.
 *
 *  @type type $var Description.
 *  @type type $var Description.
 * }
 * @param type $var Description.
 */

Use inline comments within methods and functions to clarify specific code sections.
Inline Comments

For duplicate hooks, only the first instance should be fully documented. Subsequent instances should have a single-line comment indicating where the full documentation can be found.[2]

Single-line comments: // Allow plugins to filter an array.[2]
    Multi-line comments: Use /* ... */ format, but avoid using /** ... */ as it might be mistaken for a DocBlock.[2]

Code Formatting

Use common PHPDoc tags like @since, @see, @global, @param, and @return to provide structured information about your code.[2]
PHPDoc Tags

/*
 * This is a comment that is long enough to warrant being stretched over
 * the span of multiple lines. You'll notice this follows basically
 * the same format as the PHPDoc wrapping and comment block style.
 */

Consistent code formatting is essential for readability. Key formatting guidelines include:
Best Practices

Indentation: Use tabs, not spaces, for indentation.[1] [6]
    Spacing: Add spaces after commas and around operators.[1]
    Line Length: Aim for lines of code under 80 characters to improve readability.[6]
    Brace Style: Use the standard WordPress brace style for control structures.[1]

Security: Sanitize and escape all user input and output using WordPress's built-in functions (e.g., esc_html(), esc_url(), sanitize_text_field()).[6]
    Namespacing: Use namespaces to avoid function and class name conflicts.[6]
    Modularity: Keep functions small and focused, each performing a single task.[6]
    Testing: Use WP_DEBUG during development to catch errors and enable logging for troubleshooting.[6]
    Documentation: Provide a clear README.txt file with installation instructions, usage examples, and support information.[6]

By following these recommendations, you can create well-documented, maintainable, and secure WordPress plugins that contribute positively to the WordPress ecosystem.

https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/

Anonymous

Source Code Documentation Recommendations for PHP WordPress Plugins02.07.25

Information Epoch 1772847003