Wikka "Howto" Pages

Code Documentation Tutorial


 

Code documentation


Documentation is essential! Even well-written code is not necessarily self-documenting; there is always some decision-making involved, for instance, in why you coded something the way you did, why a particular algorithm is chosen, etc. Such "why" decisions should be documented. Also, pieces of code that need to be used by others, such as classes and functions (and in Wikka this includes actions and handlers) need to have their interface documented so others can make use of the functionality without needing to read all the code first. In fact, when starting to write something new, it's a good idea to start with the documentation - and then work that out into code.
It's important that such documentation "travels with" the code, instead of having it externally. That's where comments come in, and specific guidelines for how to write comments for multiple purposes. A tool like phpDocumentor can help to make a user-friendly and cross-referenced documentation for others to use by parsing the code looking for structures like classes and functions and for structured comments, and outputting fully-crossreferenced HTML documentation.

The docblock


This section uses materials adapted from the phpDoc manual
Self-documenting code can be created by adding phpDoc docblocks. Every file, class, function and - where needed - constant or variable should be introduced by a docblock.

A docblock is an extended C++-style PHP comment that begins with /** and has an * at the beginning of every line. Every file contains a main (or page-level) docblock, followed by docblocks for specific elements always preceding the element they refer to.

/**
 * The most basic Wikka function.
 */

function foo()
{
}

A docblock contains three basic segments in this order:

Element description


The SHORT DESCRIPTION starts on the first line of a code block, and can be terminated with a blank line or a period. A period inside a word is ignored. If the Short Description becomes more than three lines long, only the first line is taken. The LONG DESCRIPTION continues for as many lines as desired and may contain html markup for display formatting. Here is a sample docblock with a Short and a Long Description:

/**
 * Display information about the system Wikka is running on.
 *
 * Depending on the 'show' parameter, this action displays different types of system information.
 * By default it only displays this information to Wikka Admins, this option can be changed by
 * setting 'public_sysinfo' to '1' in the Wikka configuration file.
 *
 *  Syntax:
 *  {{system [show="OS|machine|host"]}}
 *
 */

You can optionally use a limited set of HTML elements in the Long Description if needed. Long Descriptions can also contain lists like in the following example:

/**
 * Simple DocBlock with simple lists
 *
 * Here's a simple list:
 * - item 1
 * - item 2, this one
 *   is multi-line
 * - item 3
 * end of list.  Next list is ordered
 * 1 ordered item 1
 * 2 ordered item 2
 * end of list. This is also ordered:
 * 1. ordered item 1
 * 2. ordered item 2
 */


Tags


The last (and most important) part of a docblock contains TAGS that add information on the documented item. Tags are single words prefixed by a @ symbol.
Wikka recommends the use of a subset of all the tags supported by phpDoc (for the complete list check this page). The following is a list of standard tags used in Wikka:

@author

Define the author of current element.

@author       Author Name <author@email>
@author       {@link http://wikkawiki.org/UserPage Author Name} (further notes)   


@copyright

Define copyright information for an element.

@copyright    Copyright © 2002-2006, Wikka Development Team


@filesource

Add a link to the source of the current file. The @filesource tag can only be used in a page-level docblock, it will be ignored anywhere else.

@name    PageIndex
@package    Actions
@filesource


@ignore

Prevent the documentation of an element.

@internal

Mark documentation as private, internal to the software project. @internal can be used to facilitate the creation of two sets of documentation, one for advanced developers or for internal use, and the other for the general public.

@license

Display a hyperlink to a URL for a license

@license    http://www.gnu.org/copyleft/gpl.html GNU General Public License


@link

Display a hyperlink to a URL in the documentation. You may use the @link tag to document any element (include, page, class, function, define, method, variable).

@link sftp://ftp.wikkawiki.org
@link http://wikkawiki.org Wikka Documentation
@link http://wikkawiki.org, http://tracker.wikkawiki.org, http://demo.wikkawiki.org


{@link URL description} can also be used as an inline tag anywere in a docblock:

For further information contact the {@link http://wikkawiki.org/CreditsPage Wikka Development Team}


If you want to link to an element's documentation, use the @see tag.

@name

Specify an alias to use for a page or global variable in displayed documentation and linking.

@name  RecentChanges


@package

Specify package to group files and classes.

@package        Handlers


Package names for Wikka are: 3rdParty, Actions, Css, Core, Docs, Formatters, Handlers, Setup, Template

@see

Display a link to the documentation for an element. The @see tag may be used to document any element (global variable, include, page, class, function, define, method, variable) and it accepts an unlimited number of values separated by commas.

@see Wakka
@see Wakka::$foo
@see Wakka::IsAdmin()
@see /css/wikka.css
@see TEST_CONSTANT
@see parent_method()


@since

Document when (at which version) an element was first added to a package. If it's part of the Wikka package it should be indicated as Wikka version_number.

@since Wikka 1.1.6.2


@subpackage

Specify a sub-package to group classes or functions and defines into. Requires @package tag.

@package        Handlers
@subpackage        Page


@todo

Document changes that will be made in the future. Multiple todo items should be added separately.

@todo add credits;
@todo remove useless whitespace;


@uses

Display a link to the documentation for an element, and create a backlink in the other element's documentation. The @uses tag differs from @see in that a return link is added automatically (with the label "used by") in the referred element.

@uses Wakka::IsAdmin()
@uses /libs/Wakka.class.php
@uses parent_method()
@uses ERROR_INVALID_USERNAME


@version

Define the version of the current element. This should only be used in page-level docblocks and be set to $Id$ to use the SVN Id keyword.

@version     $Id$


On top of these standard tags, some other tags are required to document specific elements.

Documentable elements


(stub - file/class/function/constant/variable - refer to page with templates)

DocBlock templates


DocBlock templates are designed to save typing by applying the same DocBlock elements to a series of PHP statements, such as a list of private variable declarations. The start element for a DocBlock template always appears like this:

/**#@+
 *
 */


Denote the end of a DocBlock template using this syntax:

/**#@-*/


Here is an example borrowed from the phpDocumentor docs:

class Bob
{
	// beginning of docblock template area
	/**#@+
	 * @access private
	 * @var string
	 */
	var $_var1 = 'hello';
	var $_var2 = 'my';
	var $_var3 = 'name';
	/**
	 * Two words
	 */
	var $_var4 = 'like strings';
	/**#@-*/
	var $publicvar = 'Lookee me!';
}   


is parsed as if the following DocBlock elements appeared instead:

class Bob
{ 
  // beginning of docblock template area
  /** 
   * @access private
   * @var string 
   */  
  var $_var1 = 'hello';
  /** 
   * @access private
   * @var string 
   */  
  var $_var2 = 'my';
  /** 
   * @access private
   * @var string 
   */  
  var $_var3 = 'name';
  /** 
   * Two words
   * @access private
   * @var string 
   */
  var $_var4 = 'like strings';
  var $publicvar = 'Lookee me!';
}


Comments outside dockblocks

(stub)

Single-line comments vs. comment blocks

(stub)

End-of-line comments

(stub)

Special markers

(stub - conventions for things like "todo" and "fixme" remarks)


CategoryHowto
There are 2 comments on this page. [Show comments]
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki