Skip to:
Content
Pages
Categories
Search
Top
Bottom

BP PHPDoc Inline Documentation

Introduction

BuddyPress strives for the most complete internal documentation possible. When contributing patches to BuddyPress, you are highly encouraged to document your code using our standards. We also welcome patches that provide new documentation, or correct/amend existing documentation.

Standards

BuddyPress’s documentation is based on WordPress’s PHP Documentation Standards. Familiarize yourself with that document before continuing with this guide.

There are a number of ways in which BuddyPress’s standards differ from WordPress’s. They are listed below. For any aspect of inline PHP documentation not specifically discussed here, you can assume that we are doing things the WordPress way.

BuddyPress-specific standards

  • @since

    For better conformity with certain IDEs, use the format @since BuddyPress (x.y.z)

    * @since BuddyPress (1.9.0)
  • Short description

    For consistency, short descriptions should be written as imperatives: “Fetch a piece of metadata about a group” rather than “Fetches a piece of metadata….”

  • Vertical alignment – @param, @return

    Multi-line descriptions should be aligned with the param type (not Description, as in WP).

    * @param int|array $group_id The ID of a single group, or an array containing
             multiple group IDs.

    We differ with WP on this point to allow for more verbose descriptions, when necessary.

  • PHPDoc Tags – order and grouping

    Doc blocks can contain a number of tags. Not all are always required, but when present, they should be grouped and ordered as follows:

    /**
     * Short description.
     *
     * Long description.
     *
     * @since BuddyPress (1.9.0)
     * @access private
     *
     * @see Function/method/class relied on
     * @link URL
     * @global type $varname Short description.
     *
     * @param type $var Description.
     * @return type Description.
     */