Skip to content

Documentation Standards

Jump to bottom
Lauren Mancke edited this page Apr 5, 2017 · 2 revisions

Documentation within themes provides a good resource for other developers and users in customizing themes. The Genesis Child Theme documentation standards are based on the WordPress Documentation Standards and those used in the Genesis Framework.

Documenting Tips & Grammar

  • Descriptive elements should be written as complete sentences. They should be clear, simple, and brief. Avoid describing “why” an element exists, rather, focus on documenting “what” and “when” it does something. (e.g. What does the function do? What is being filtered? When does an action fire?)

  • A function, hook, class, or method is a third-person singular element, meaning that third-person singular verbs should be used to describe what each does.

    Good: “(It) Does something.”
    Bad: “(It) Do something.”

  • A serial (Oxford) comma should be used when listing elements in summaries, descriptions, and parameter or return descriptions.

Formating Guidelines

Documentation mostly takes the form of either formatted blocks of documentation (DocBlocks) or inline comments.

DocBlocks

The examples provided in each section below show the expected DocBlock content and tags, as well as the exact formatting.

  • Spaces: Use spaces inside the DocBlock, not tabs, and ensure that items in each tag group are aligned according to the examples.

  • Line Wrapping: DocBlock text should wrap to the next line after 80 characters of text. If the DocBlock itself is indented on the left 20 character positions, the wrap could occur at position 100, but should not extend beyond a total of 120 characters wide.

1. File Headers

The file header DocBlock is used to give an overview of what is contained in the file. Whenever possible, all theme files should contain a header DocBlock, regardless of the file’s contents. The file header DocBlock should be formatted as follows:

/**
 * Theme Name.
 *
 * Description.
 *
 * @package Theme
 * @author  StudioPress
 * @license GPL-2.0+
 * @link    Theme URL
 */
  • Theme Name: The name of the theme in title case. Use a period at the end.
  • Description: A brief, one sentence explanation of the purpose of the file spanning a maximum of two lines. Use a period at the end.
  • Package: Specifies package that all functions, includes, and defines in the file belong to. The @package name for themes should be the theme name, spaced with underscores: Digital_Pro.
  • Author: Identifies the author of the theme.
  • License: Documents the software license that applies to this code which is GPL-2.0+.
  • Link: Links to the theme on StudioPress: http://my.studiopress.com/themes/digital/. Always use a trailing slash.

Template files should include the template name within the file heading DocBlock:

/**
 * Digital Pro.
 *
 * This file adds the landing page template to the Digital Pro Theme.
 *
 * Template Name: Landing
 *
 * @package Digital_Pro
 * @author  StudioPress
 * @license GPL-2.0+
 * @link    http://my.studiopress.com/themes/digital/
 */

2. Functions, Classes, Hooks, and Filters

Placement:

DocBlocks should directly precede the function, method, or class line. Both action and filter hooks should be documented on the line immediately following the call to add_action() or add_filter(). For example:

add_filter( 'genesis_theme_settings_defaults', 'digital_theme_defaults' );
/**
 * Updates theme settings on reset.
 *
 * @since 1.0.0
 */
function digital_theme_defaults( $defaults ) {

Formatting:

DocBlocks for Functions, Classes, Actions and Filters can contain a summary, description, and appropriate tags. They should be formatted as follows:

/**
 * 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.
 */
  • Summary: A brief, one sentence explanation of the purpose of the function spanning a maximum of two lines. Use a period at the end. No HTML markup or Markdown of any kind should be used in the summary. If the text refers to an HTML element or tag, then it should be written as “image tag” or “img” element, not <img>.
  • Description: A supplement to the summary, providing a more detailed description. Use a period at the end of sentences. HTML markup should never be used outside of code examples, though Markdown can be used, as needed, in the description. More examples of Long Descriptions are in the WordPress Coding Standards section of the handbook.
  • since x.x.x: Should always be 3-digit (e.g. @since 3.9.0).
  • see: Reference to a function, method, or class that is heavily-relied on within.
  • link: URL that provides more information. This should never been used to reference another function, hook, class, or method. Use @see instead.
  • global: List PHP globals that are used within the function or method, with an optional description of the global. If multiple globals are listed, they should be aligned by type, variable, and description, with each other as a group.
  • param: Note if the parameter is Optional before the description, and include a period at the end. The description should mention accepted values as well as the default. For example: Optional. This value does something. Accepts ‘post’, ‘term’, or empty. Default empty.
  • return: Should contain all possible return types, and a description for each. Use a period at the end. Note that @return is not used for hook or filter documentation, because action hooks return nothing, and filter hooks always return their first parameter.

Note: Common PHPDoc tags used in WordPress include @since, @see, @global, @param, and @return (see the supported PHPDocs table for full list). Also see the supported JSDoc tags for documentation in JavaScript files.

Inline Comments

Inline comments inside methods and functions should be formatted as follows:

1. Single line comments

// Adds front-page body class.

Note: Single-line comments must begin with // and end with a . period.

2. Multi-line comments

/* 
 * 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.
 */

Note: Multi-line comments must not begin with /** (double asterisk) as it might be mistaken for a DocBlock. Use /* (single asterisk) instead.

Duplicate Hooks

There are common hooks and functions that are used multiple times in child theme files. In these cases, rather than list the entire DocBlock every time, a single-line comment can be used.

// Adds viewport meta tag for mobile browsers.
add_theme_support( 'genesis-responsive-viewport' );

Requires and Includes

Files required or included can be documented with a single-line comment for consistency within the functions file.

// Starts the engine.
include_once( get_template_directory() . '/lib/init.php' );

Best Practices

Clone this wiki locally