1.5 Template Project

The Joomla! Documentation Working Group is running a project to develop detailed reference and tutorial material on Joomla! 1.5 templates.  There is a project page on the documentation wiki where you can see the work in progress and help us by contributing your knowledge.

Who's Online

We have 8 guests online

Help Site License

The Joomla! Help Site content is copyright © 2005 - 2008 by the individual contributors and can be used in accordance with the Creative Commons License, Attribution NonCommercial ShareAlike 2.5. Some parts of this website may be subject to other licenses.
Home arrow Developer Manual arrow 10. Development Standards arrow Comment Coding Standards

Comment Coding Standards PDF Print E-mail
Start Of the Document
/**
 * Joomla Coding Documentation Quickstart
 *
 * This file demonstrates the rich information
 * that can be included in-code and subsequently
 * used to generate documentation for Joomla!
 * components using phpDocumentor
 *
 * This is a copy of sample2.php by Greg Beaver of
 * php.net and is provided with phpDocumentor package.
 *
 * @author copy/pasted by Predator
 * @package sample
 */


Add descriptions to included files
/**
 * Provide a description of 'include' or 'required'
 * and its purpose
 */
include_once 'sample3.php';

Use special declaration for global variables.
/**
 * Special global variable declaration DocBlock
 * @global integer $GLOBALS['_myvar']
 * @name $_myvar
 */
$GLOBALS['_myvar'] = 6;

Use special declaration for Constants.
/**#@+
 * Constants
 */
/**
 * first constant
 */
define('testing', 6);
/**
 * second constant
 */
define('anotherconstant', strlen('hello'));
 
/**#@-*/

Functions or Methods have lots of valuable information you can declare
/**
 * A sample function docblock
 * @global string document that this function uses $_myvar
 * @staticvar integer $staticvar this is what is returned
 * @param string $param1 name to declare
 * @param string $param2 value of the name
 * @return integer
 */
function firstFunc($param1, $param2 = 'optional')
{
    static $staticvar = 7;
    global $_myvar;
    return $staticvar;
}
<
Many special declarations for Classes as well.
/**
 * The first example class, this is in the same
 * package as declared at the start of file but
 * this example has a defined subpackage
 * @package sample
 * @subpackage classes
 */
class myclass {
    /**
     * A sample private variable, this can be hidden with the --parseprivate
     * option
     * @access private
     * @var integer|string
     */
    var $firstvar = 6;
    /**
     * @link http://www.example.com Example link
     * @see myclass()
     * @uses testing, anotherconstant
     * @var array
     */
    var $secondvar =
        array
            'stuff' =>
                array(
                    6,
                    17,
                    'armadillo'
                ),
            testing => anotherconstant
        );
 
    /**
     * Constructor sets up {@link $firstvar}
     */
    function myclass()
    {
        $this->firstvar = 7;
    }
 
    /**
     * Return a thingie based on $paramie
     * @param boolean $paramie
     * @return integer|babyclass
     */
    function parentfunc($paramie)
    {
        if ($paramie) {
            return 6;
        } else {
            return new babyclass;
        }
    }
}

Here is a child class of the previous example.
/**
 * @package sample1
 */
class babyclass extends myclass {
    /**
     * The answer to Life, the Universe and Everything
     * @var integer
     */
    var $secondvar = 42;
    /**
     * Configuration values
     * @var array
     */
    var $thirdvar;
 
    /**
     * Calls parent constructor, then increments {@link $firstvar}
     */
    function babyclass()
    {
        parent::myclass();
        $this->firstvar++;
    }
 
    /**
     * This always returns a myclass
     * @param ignored $paramie
     * @return myclass
     */
    function parentfunc($paramie)
    {
        return new myclass;
    }
} <!--</body-->
Last Updated ( Thursday, 08 December 2005 )
 
< Prev