Revision [14754]
This is an old revision of DocumentingCodeHowto made by DarTar on 2006-06-30 12:40:13.
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.
phpDoc docblocks
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. Docblocks always precede the element they are documenting.
/**
* The most basic Wikka function.
*/
function foo()
{
}
* The most basic Wikka function.
*/
function foo()
{
}
A docblock contains three basic segments in this order:
- Short Description
- Long Description
- Tags
/**
* 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"]}}
*
*/
* 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
*/
* 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
*/
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):
(stub)
@access
@access public or private
@author
@author Author Name <author@email> @author {@link http://wikkawiki.org/UserPage Author Name} (further notes)
@copyright
@copyright Copyright © 2002-2006, Wikka Development Team
@license
@license http://www.gnu.org/copyleft/gpl.html GNU General Public License
@link
@link http://wikkawiki.org
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}
@name
@name RecentChanges
@package
@package Handlers
@see
@see Wakka::IsAdmin() @see /css/wikka.css
@since
@since Wikka 1.1.6.2
@subpackage
@package Handlers @subpackage Page
@todo
@todo add credits; @todo remove useless whitespace;
@version
@version $Id$
On top of these general tags, specific tags are required to document different elements.
Documentable elements
(stub)(stub - file/class/function/constant/variable - refer to page with templates)
Single-line comments vs. comment blocks
(stub)End-of-line comments
(stub)Special markers
(stub - conventions for things like "todo" and "fixme" remarks)CategoryHowto