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

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.
@deprecatedoptional
@linkoptional
@seeoptional
@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 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;
        }
}
Continued Education in Course Joomla 3
You are viewing Section 14: DocBlocks - Documentation headers in Joomla
Section 13: @package - Joomla DocBlock headers
Section 15: Updating article hits when using Joomla cache
Did you find this article helpful?

We value your feedback!

Why was this article not helpful? (Check all that apply)
The article is too difficult or too technical to follow.
There is a step or detail missing from the instructions.
The information is incorrect or out-of-date.
It does not resolve the question/problem I have.
How did you find this article?
Please tell us how we can improve this article:
Email Address
Name

new! - Enter your name and email address above and we will post your feedback in the comments on this page!

Related Questions

Here are a few questions related to this article that our customers have asked:
Ooops! It looks like there are no questions about this page.
Would you like to ask a question about this page? If so, click the button below!
Ask a Question

Joomla Community Google+ Hangout #3

June 3rd, 2014

Thank you @RustyJoomla for letting me speak on the Joomla Community Google+ Hangout!

Click here to watch!

Post a Comment

Name:
Email Address:
Phone Number:
Comment:
Submit

Please note: Your name and comment will be displayed, but we will not show your email address.

0 Questions & Comments

Post a comment

Back to first comment | top

Need more Help?

Search

Ask the Community!

Get help with your questions from our community of like-minded hosting users and InMotion Hosting Staff.

Current Customers

Chat: Click to Chat Now E-mail: support@InMotionHosting.com
Call: 888-321-HOST (4678) Ticket: Submit a Support Ticket

Not a Customer?

Get web hosting from a company that is here to help. Sign up today!