Actions

Difference between revisions of "Coding style and standards/Comments"

From Joomla! Documentation

< Coding style and standards
m (Reference:Joomla! Comment Standards moved to Coding style and standards/Comments: Moved page to keep related pages together)
(Made miscellaneous improvements)
 
Line 1: Line 1:
===== Joomla! Comment Standards =====
 
 
=== 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.
 
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.
 
  
 +
=== Start the file with a descriptive comment ===
  
 
<source lang="php">
 
<source lang="php">
Line 24: Line 20:
 
</source>
 
</source>
  
=== Add descriptions to included files ===
+
=== Add descriptions to <code>include</code>s ===
  
 
<source lang="php">
 
<source lang="php">
Line 34: Line 30:
 
</source>
 
</source>
  
=== Use special declaration for global variables. ===
+
=== Use special declarations for global variables ===
 +
 
 +
''Warning: this section might be outdated.''
  
 
<source lang="php">
 
<source lang="php">
Line 45: Line 43:
 
</source>
 
</source>
  
=== Use special declaration for Constants. ===
+
=== Use special declarations for constants ===
  
 
<source lang="php">
 
<source lang="php">
Line 63: Line 61:
 
</source>
 
</source>
  
=== Functions or Methods have lots of valuable information you can declare ===
+
=== Add valuable information to function and method declarations ===
  
 
<source lang="php">
 
<source lang="php">
Line 81: Line 79:
 
</source>
 
</source>
  
=== Many special declarations for Classes as well. ===
+
=== Add specific information to class declarations ===
  
 
<source lang="php">
 
<source lang="php">
Line 138: Line 136:
 
</source>
 
</source>
  
=== Here is a child class of the previous example. ===
+
=== A subclass example ===
  
 
<source lang="php">
 
<source lang="php">
Line 174: Line 172:
 
}
 
}
 
</source>
 
</source>
 
[[:start|Back to the Startpage]]
 

Latest revision as of 12:18, 28 January 2011

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.

Contents

Start the file with a descriptive comment

/**
 * 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 < Smiley >
 * @package sample
 */

Add descriptions to includes

/**
 * Provide a description of 'include' or 'required'
 * and its purpose
 */
include_once 'sample3.php';

Use special declarations for global variables

Warning: this section might be outdated.

/**
 * Special global variable declaration DocBlock
 * @global integer $GLOBALS['_myvar']
 * @name $_myvar
 */
$GLOBALS['_myvar'] = 6;

Use special declarations for constants

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

Add valuable information to function and method declarations

/**
 * 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;
}

Add specific information to class declarations

/**
 * 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;
        }
    }
}

A subclass 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;
    }
}