DocBlocks - Documentation headers in Joomla

The knowledge is this article has been obtained from this page. While learning about DocBlocks, we felt the information in that article would be more easily absorbed if reformatted.

What is a DocBlock?

DocBlocks, short for Documentation Blocks, are notes that describe what certain sections of code do.

There are 1000’s of lines of code within Joomla. Documentation blocks (written by the developers) help others looking at the code understand what exactly the code is / does.

Where do DocBlocks go?

DocBlocks go above the code it is describing, but not every section of code needs a DocBlock above it. The following is a list of where within Joomla code DocBlocks are needed:

Files
Class Definitions
Class Properties
Class Methods

DocBlock Formatting

Spaces, not tabs	Instead of using a tab / indent, use two spaces.
Credit	Instead of getting credit for the code you’ve contributed using the @author tag, update the CREDITS.php file.
3rd Party Code	Leave 3rd party DocBlocks as they are.

DocBlock Headers

The type of information found within a DocBlock is categorized into different “headers”, and some headers are required while others are not.

Below is a list of optional / required headers, along with helpful notes.

The headers should be written in the order they are found below!

DocBlock Types:

Files Class Definitions Class Properties Class Methods

Files

Header	Requirement	Additional notes
Short description	optional	Optional, unless the file contains more than two classes or functions. Followed by a blank line.
Long Description	optional	Followed by a blank line.
@category	optional	Rarely used
@package	generally optional	Required when files contain only procedural code
@subpackage	optional
@author	optional	Only allowed on non-joomla source files (like 3rd party extensions)
@copyright	required
@license	required	Must be compatible with the Joomla license
@deprecated	optional
@link	optional
@see	optional
@since	generally optional	Required when files contain only procedural code

Example File DocBlock

 <?php /**  * @package     Joomla.Platform  * @subpackage  Database  *  * @copyright   Copyright (C) 2005 - 2014 Open Source Matters, Inc. All rights reserved.  * @license     GNU General Public License version 2 or later; see LICENSE  */  defined('JPATH_PLATFORM') or die;

Class Definition

Header	Requirement	Additional notes
Short Description	required	Unless the file contains more than two classes or functions Followed by a blank line.
Long Description	optional	Followed by a blank line.
@category	optional	Rarely used.
@package	required
@subpackage	optional
@author	optional	Only allowed on non-joomla source files (like 3rd party extensions)
@copyright	optional	Unless different from the file DocBlock.
@license	optional	Unless different from the file DocBlock.
@deprecated	optional
@link	optional
@see	optional
@since	required	@since should be the version of the software the class was introduced.

Example Class Definition DocBlock

 /**  * Controller class to initialise the database for the Joomla Installer.  *  * @package     Joomla.Installation  * @subpackage  Controller  * @since       3.1  */

Class Property

Header	Requirement	Additional notes
Short Description	required	Unless the file contains more than two classes or functions Followed by a blank line.
@var	required	Followed by the property type.
@deprecated	optional
@since	required

Example Class Property DocBlock

     /**      * The generated user ID      *      * @var    integer      * @since  3.1      */     protected static $userId = 0;

Class Method / Function

Header	Requirement	Additional notes
Short Description	required	Unless the file contains more than two classes or functions Followed by a blank line.
Long Description	optional	Followed by a blank line.
@param	required	Required if there are method or function arguments. The last @param tag is followed by a blank line.
@return	required	Followed by a blank line.
@since	required

Example Class Method DocBlock

     /**      * Set a controller class suffix for a given HTTP method.      *      * @package Joomla.Framework      * @subpackage Router       *      *      * @param   string  $method  The HTTP method for which to set the class suffix.      * @param   string  $suffix  The class suffix to use when fetching the controller name for a given request.      *      * @return  Router  Returns itself to support chaining.      *      * @since   1.0      */     public function setHttpMethodSuffix($method, $suffix)

Example file

Now that we’ve finished our review of the do’s and don’ts of DocBlocks, let’s see them in action. Below is an actual file from Joomla! – components/com_content/models/categories.php. We’ve highlighted the various DocBlock types in different colors to make it easier to review.

File DocBlock	highlighted in red
Class Definition DocBlock	highlighted in green
Class Property DocBlock	highlighted in orange
Class Method DocBlock	highlighted in purple

 EXAMPLE FILE: components/com_content/models/categories.php  <?php /**  * @package     Joomla.Site  * @subpackage  com_content  *  * @copyright   Copyright (C) 2005 - 2014 Open Source Matters, Inc. All rights reserved.  * @license     GNU General Public License version 2 or later; see LICENSE.txt  */  defined('_JEXEC') or die;  /**  * This models supports retrieving lists of article categories.  *  * @package     Joomla.Site  * @subpackage  com_content  * @since       1.6  */ class ContentModelCategories extends JModelList {         /**          * Model context string.          *          * @var         string          */         public $_context = 'com_content.categories';          /**          * The category context (allows other extensions to derived from this model).          *          * @var         string          */         protected $_extension = 'com_content';          private $_parent = null;          private $_items = null;          /**          * Method to auto-populate the model state.          *          * Note. Calling getState in this method will result in recursion.          *          * @since   1.6          */         protected function populateState($ordering = null, $direction = null)         {                 $app = JFactory::getApplication();                 $this->setState('filter.extension', $this->_extension);                  // Get the parent id if defined.                 $parentId = $app->input->getInt('id');                 $this->setState('filter.parentId', $parentId);                  $params = $app->getParams();                 $this->setState('params', $params);                  $this->setState('filter.published',     1);                 $this->setState('filter.access',        true);         }          /**          * Method to get a store id based on model configuration state.          *          * This is necessary because the model is used by the component and          * different modules that might need different sets of data or different          * ordering requirements.          *          * @param   string  $id A prefix for the store id.          *          * @return  string  A store id.          */         protected function getStoreId($id = '')         {                 // Compile the store id.                 $id     .= ':'.$this->getState('filter.extension');                 $id     .= ':'.$this->getState('filter.published');                 $id     .= ':'.$this->getState('filter.access');                 $id     .= ':'.$this->getState('filter.parentId');                  return parent::getStoreId($id);         }          /**          * Redefine the function an add some properties to make the styling more easy          *          * @param   bool        $recursive      True if you want to return children recursively.          *          * @return  mixed  An array of data items on success, false on failure.          * @since   1.6          */         public function getItems($recursive = false)         {                 if (!count($this->_items))                 {                         $app = JFactory::getApplication();                         $menu = $app->getMenu();                         $active = $menu->getActive();                         $params = new JRegistry;                          if ($active)                         {                                 $params->loadString($active->params);                         }                          $options = array();                         $options['countItems'] = $params->get('show_cat_num_articles_cat', 1) || !$params->get('show_empty_categories_cat', 0);                         $categories = JCategories::getInstance('Content', $options);                         $this->_parent = $categories->get($this->getState('filter.parentId', 'root'));                          if (is_object($this->_parent))                         {                                 $this->_items = $this->_parent->getChildren($recursive);                         }                         else {                                 $this->_items = false;                         }                 }                  return $this->_items;         }          public function getParent()         {                 if (!is_object($this->_parent))                 {                         $this->getItems();                 }                  return $this->_parent;         } }

DocBlocks – Documentation headers in Joomla