BP PHPDoc Inline Documentation
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.
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.
For better conformity with certain IDEs, use the format
@since BuddyPress (x.y.z)
* @since BuddyPress (1.9.0)
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 –
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. */