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 |
|
|---|---|
| Credit |
|
| 3rd Party Code |
|
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 |
|
| 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 |
|
| 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 |
|
| @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 |
|
| Long Description | optional | Followed by a blank line. |
| @param | required |
|
| @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; } }
