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

HeaderRequirementAdditional notes
Short descriptionoptional
  • Optional, unless the file contains more than two classes or functions.
  • Followed by a blank line.
Long DescriptionoptionalFollowed by a blank line.
@categoryoptionalRarely used
@packagegenerally optionalRequired when files contain only procedural code
@subpackageoptional
@authoroptionalOnly allowed on non-joomla source files (like 3rd party extensions)
@copyrightrequired
@licenserequiredMust be compatible with the Joomla license
@deprecatedoptional
@linkoptional
@seeoptional
@sincegenerally optionalRequired 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

HeaderRequirementAdditional notes
Short Descriptionrequired
  • Unless the file contains more than two classes or functions
  • Followed by a blank line.
Long DescriptionoptionalFollowed by a blank line.
@categoryoptionalRarely used.
@packagerequired
@subpackageoptional
@authoroptionalOnly allowed on non-joomla source files (like 3rd party extensions)
@copyrightoptionalUnless different from the file DocBlock.
@licenseoptionalUnless different from the file DocBlock.
@deprecatedoptional
@linkoptional
@seeoptional
@sincerequired@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

HeaderRequirementAdditional notes
Short Descriptionrequired
  • Unless the file contains more than two classes or functions
  • Followed by a blank line.
@varrequiredFollowed by the property type.
@deprecatedoptional
@sincerequired

Example Class Property DocBlock

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

Class Method / Function

HeaderRequirementAdditional notes
Short Descriptionrequired
  • Unless the file contains more than two classes or functions
  • Followed by a blank line.
Long DescriptionoptionalFollowed by a blank line.
@paramrequired
  • Required if there are method or function arguments.
  • The last @param tag is followed by a blank line.
@returnrequiredFollowed by a blank line.
@sincerequired

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 DocBlockhighlighted in red
Class Definition DocBlockhighlighted in green
Class Property DocBlockhighlighted in orange
Class Method DocBlockhighlighted 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;         } }

Comments

It looks like this article doesn't have any comments yet - you can be the first. If you have any comments or questions, start the conversation!

Was this article helpful? Let us know!