Revision history for DocumentingCodeHowto
Revision [19112]
Last edited on 2008-01-28 00:14:03 by DarTar [Modified links pointing to docs server]No Differences
Additions:
@uses ERROR_INVALID_USERNAME
Additions:
var $_var4 = 'like strings';
Deletions:
Additions:
===""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 $_var8 = 'like strings';
var $publicvar = 'Lookee me!';
""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 $_var8 = 'like strings';
var $publicvar = 'Lookee me!';
No Differences
Additions:
Wikka recommends the use of a subset of all the tags supported by phpDoc (for the complete list check [[http://manual.phpdoc.org/HTMLframesConverter/DOM/default/phpDocumentor/tutorial_tags.pkg.html this page]]). The following is a list of standard tags used in Wikka:
Deletions:
Additions:
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.
Deletions:
Additions:
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 (//page-level//) dockblock, followed by docblocks for specific elements always //preceding// the element they refer to.
Deletions:
No Differences
Additions:
<li><a href="http://wikkawiki.org/DocumentingCodeHowto#hn_Code_documentation">Code documentation</a></li>
<li><a href="http://wikkawiki.org/DocumentingCodeHowto#hn_The_docblock">The docblock</a></li>
<li><a href="http://wikkawiki.org/DocumentingCodeHowto#hn_Element_description">Element description</a></li>
<li><a href="http://wikkawiki.org/DocumentingCodeHowto#hn_Tags">Tags</a></li>
<li><a href="http://wikkawiki.org/DocumentingCodeHowto#hn_Documentable_elements">Documentable elements</a></li>
<li><a href="http://wikkawiki.org/DocumentingCodeHowto#hn_Comments_outside_dockblocks">Comments outside docblocks</a></li>
<li><a href="http://wikkawiki.org/DocumentingCodeHowto#hn_Single-line_comments_vs._comment_blocks">Single-line comments vs. comment blocks</a></li>
<li><a href="http://wikkawiki.org/DocumentingCodeHowto#hn_End-of-line_comments">End-of-line comments</a></li>
<li><a href="http://wikkawiki.org/DocumentingCodeHowto#hn_Special_markers">Special markers</a></li>
<li><a href="http://wikkawiki.org/DocumentingCodeHowto#hn_The_docblock">The docblock</a></li>
<li><a href="http://wikkawiki.org/DocumentingCodeHowto#hn_Element_description">Element description</a></li>
<li><a href="http://wikkawiki.org/DocumentingCodeHowto#hn_Tags">Tags</a></li>
<li><a href="http://wikkawiki.org/DocumentingCodeHowto#hn_Documentable_elements">Documentable elements</a></li>
<li><a href="http://wikkawiki.org/DocumentingCodeHowto#hn_Comments_outside_dockblocks">Comments outside docblocks</a></li>
<li><a href="http://wikkawiki.org/DocumentingCodeHowto#hn_Single-line_comments_vs._comment_blocks">Single-line comments vs. comment blocks</a></li>
<li><a href="http://wikkawiki.org/DocumentingCodeHowto#hn_End-of-line_comments">End-of-line comments</a></li>
<li><a href="http://wikkawiki.org/DocumentingCodeHowto#hn_Special_markers">Special markers</a></li>
Deletions:
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_The_docblock">The docblock</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Element_description">Element description</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Tags">Tags</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Documentable_elements">Documentable elements</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Comments_outside_dockblocks">Comments outside docblocks</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Single-line_comments_vs._comment_blocks">Single-line comments vs. comment blocks</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_End-of-line_comments">End-of-line comments</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Special_markers">Special markers</a></li>
Additions:
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_The_docblock">The docblock</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Element_description">Element description</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Tags">Tags</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Documentable_elements">Documentable elements</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Comments_outside_dockblocks">Comments outside docblocks</a></li>
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.
===The docblock===
===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:
===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.
===Documentable elements===
====Comments outside dockblocks====
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Element_description">Element description</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Tags">Tags</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Documentable_elements">Documentable elements</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Comments_outside_dockblocks">Comments outside docblocks</a></li>
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.
===The docblock===
===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:
===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.
===Documentable elements===
====Comments outside dockblocks====
Deletions:
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.
===phpDoc docblocks===
The **SHORT DESCRIPTION** starts on the first line, 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:
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.
====Documentable elements====
Additions:
Document changes that will be made in the future. Multiple todo items should be added separately.
Deletions:
Additions:
Wikka recommends the use of a subset of all the tags supported by phpDoc (for the complete list check [[http://manual.phpdoc.org/HTMLframesConverter/DOM/default/phpDocumentor/tutorial_tags.pkg.html this page]]). Standard tags used in Wikka:
Define the author of current element.
Define copyright information for an element.
**@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.
Display a hyperlink to a URL for a license
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:
If you want to link to an element's documentation, use the ##@see## tag.
Specify an alias to use for a page or global variable in displayed documentation and linking.
Specify package to group files and classes.
Package names for Wikka are: ##3rdParty, Actions, Css, Core, Docs, Formatters, Handlers, Setup, Template##
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 TEST_CONSTANT
@see parent_method()
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##.
Specify a sub-package to group classes or functions and defines into. Requires ##@package## tag.
Document changes that will be made in the future. Single todo reminders should be added as separate items.
**@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()
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.
On top of these standard tags, some other tags are required to document specific elements.
Define the author of current element.
Define copyright information for an element.
**@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.
Display a hyperlink to a URL for a license
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:
If you want to link to an element's documentation, use the ##@see## tag.
Specify an alias to use for a page or global variable in displayed documentation and linking.
Specify package to group files and classes.
Package names for Wikka are: ##3rdParty, Actions, Css, Core, Docs, Formatters, Handlers, Setup, Template##
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 TEST_CONSTANT
@see parent_method()
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##.
Specify a sub-package to group classes or functions and defines into. Requires ##@package## tag.
Document changes that will be made in the future. Single todo reminders should be added as separate items.
**@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()
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.
On top of these standard tags, some other tags are required to document specific elements.
Deletions:
**@access**
@access public or private
@link http://wikkawiki.org
Can also be used as an inline tag anywere in a docblock:
On top of these general tags, specific tags are required to document different elements.
Additions:
**@version**
@version $Id$
@version $Id$
Additions:
The **SHORT DESCRIPTION** starts on the first line, 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:
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.
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.
Deletions:
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.
Additions:
**@license**
@license http://www.gnu.org/copyleft/gpl.html GNU General Public License
@license http://www.gnu.org/copyleft/gpl.html GNU General Public License
Additions:
Wikka recommends the use of a subset of all the tags supported by phpDoc (for the complete list check [[http://manual.phpdoc.org/HTMLframesConverter/DOM/default/phpDocumentor/tutorial_tags.pkg.html this page]]):
**@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
**@name**
@name RecentChanges
**@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}
**@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;
On top of these general tags, specific tags are required to document different elements.
====Documentable elements====
""<!--
-->""
**@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
**@name**
@name RecentChanges
**@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}
**@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;
On top of these general tags, specific tags are required to document different elements.
====Documentable elements====
""<!--
-->""
Deletions:
Additions:
~-[[CodingGuidelinesHowto Wikka Coding Guidelines]]
Deletions:
Additions:
[[WikkaHowto Wikka "Howto" Pages]]
=====Code Documentation Tutorial=====
>>==See also:==
~-[[WikkaCodingGuidelinesHowto Wikka Coding Guidelines]]
>><<==Table of contents==""<ul>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Code_documentation">Code documentation</a></li>
<ul>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_phpDoc_docblocks">phpDoc docblocks</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Single-line_comments_vs._comment_blocks">Single-line comments vs. comment blocks</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_End-of-line_comments">End-of-line comments</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Special_markers">Special markers</a></li>
</ul>
</ul>""<<::c::
====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 [[http://www.phpdoc.org 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 [[http://manual.phpdoc.org/HTMLframesConverter/DOM/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.docblock 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()
{
}
A docblock contains three basic segments in this order:
~-Short Description
~-Long Description
~-Tags
The **Short Description** starts on the first line, 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 [[http://manual.phpdoc.org/HTMLframesConverter/DOM/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.desc 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
%%
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 uses a subset of all the possible tags supported by phpDoc (for the complete list of phpDoc tags check [[http://manual.phpdoc.org/HTMLframesConverter/DOM/default/phpDocumentor/tutorial_tags.pkg.html this page]])
* A short description
* As many lines of extendend description as you want {@link element}
* links to an element {@link http://www.example.com Example} links to
* a website.
* @access public or private
* @author Author Name <author@email>
or
* @author {@link http://wikkawiki.org/UserPage author name} (further notes)
* @copyright name date
* @deprecated description
* @example /path/to/example (include an external example file with syntax highlighting)
* @global type $globalvarname
or
* @global type description of global variable usage in a function
* @ignore
* @internal private information for advanced developers only
* @link URL
* @name Name of the handler/action/formatter, e.g. recentchanges
* @package package name, e.g. Handlers
* @param type [$varname] description
* @return type description
* @see name of another element that can be documented (displays an internal link to the documentation for that element)
* @since Wikka version number
* @subpackage sub package name, e.g. Page (for page handlers)
* @todo item for a todo lisy
* @var type a data type for a class variable
* @version version (will use SVN $Id$)
function foo()
{
// ...
}
(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
=====Code Documentation Tutorial=====
>>==See also:==
~-[[WikkaCodingGuidelinesHowto Wikka Coding Guidelines]]
>><<==Table of contents==""<ul>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Code_documentation">Code documentation</a></li>
<ul>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_phpDoc_docblocks">phpDoc docblocks</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Single-line_comments_vs._comment_blocks">Single-line comments vs. comment blocks</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_End-of-line_comments">End-of-line comments</a></li>
<li><a href="http://wikkawiki.org/WikkaCodingGuidelinesHowto#hn_Special_markers">Special markers</a></li>
</ul>
</ul>""<<::c::
====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 [[http://www.phpdoc.org 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 [[http://manual.phpdoc.org/HTMLframesConverter/DOM/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.docblock 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()
{
}
A docblock contains three basic segments in this order:
~-Short Description
~-Long Description
~-Tags
The **Short Description** starts on the first line, 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 [[http://manual.phpdoc.org/HTMLframesConverter/DOM/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.desc 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
%%
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 uses a subset of all the possible tags supported by phpDoc (for the complete list of phpDoc tags check [[http://manual.phpdoc.org/HTMLframesConverter/DOM/default/phpDocumentor/tutorial_tags.pkg.html this page]])
* A short description
* As many lines of extendend description as you want {@link element}
* links to an element {@link http://www.example.com Example} links to
* a website.
* @access public or private
* @author Author Name <author@email>
or
* @author {@link http://wikkawiki.org/UserPage author name} (further notes)
* @copyright name date
* @deprecated description
* @example /path/to/example (include an external example file with syntax highlighting)
* @global type $globalvarname
or
* @global type description of global variable usage in a function
* @ignore
* @internal private information for advanced developers only
* @link URL
* @name Name of the handler/action/formatter, e.g. recentchanges
* @package package name, e.g. Handlers
* @param type [$varname] description
* @return type description
* @see name of another element that can be documented (displays an internal link to the documentation for that element)
* @since Wikka version number
* @subpackage sub package name, e.g. Page (for page handlers)
* @todo item for a todo lisy
* @var type a data type for a class variable
* @version version (will use SVN $Id$)
function foo()
{
// ...
}
(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
Deletions:
This page tries to explain the way code is documented in wikka. This should be done to make it easier for other people to understand what the code is doing and why.
===Documenting Actions and functions===
Every action and function should have a documenting block at its beginning. This could be used, for example, for automatic-generatied documentation.
This block follows the following standard:
==Generell==
- it begins with a slash and two asterix: %%(php) /** %%
- each line has an asterix at the beginning: %%(php) * %%
- it ends with an asterix and a slash: %%(php) */ %%
Example:
* This is a text.
==Special Phrases==
Special expressions are words with an '@' at the beginning. The following could be used:
@package
@subpackage
@name
@author
@license
@copyright
@version
@input
@output
@uses
@todo
==Links==
//follows//
==Template for Actions==
//not finished//
<?
* The first sentence should descripe the action and must end with a dot.
* Here follows the long version of the description.
* Another part of the description.
* @package Action
* @subpackage //choose one
* @name //the name of this action
* @author
* @license
* @copyright
* @version
* @input
* @output
* @uses
* @todo
//more follows//
[[CategoryHowto]]
Additions:
Every action and function should have a documenting block at its beginning. This could be used, for example, for automatic-generatied documentation.
This block follows the following standard:
==Generell==
- it begins with a slash and two asterix: %%(php) /** %%
- each line has an asterix at the beginning: %%(php) * %%
- it ends with an asterix and a slash: %%(php) */ %%
Example:
%%(php)
/**
* This is a text.
*
*/
%%
==Special Phrases==
Special expressions are words with an '@' at the beginning. The following could be used:
@package
@subpackage
@name
@author
@license
@copyright
@version
@input
@output
@uses
@todo
==Links==
//follows//
==Template for Actions==
//not finished//
%%(php)
<?
/**
* The first sentence should descripe the action and must end with a dot.
*
* Here follows the long version of the description.
*
* Another part of the description.
*
* @package Action
* @subpackage //choose one
* @name //the name of this action
*
* @author
* @license
* @copyright
* @version
*
* @input
* @output
*
* @uses
* @todo
*/
%%
This block follows the following standard:
==Generell==
- it begins with a slash and two asterix: %%(php) /** %%
- each line has an asterix at the beginning: %%(php) * %%
- it ends with an asterix and a slash: %%(php) */ %%
Example:
%%(php)
/**
* This is a text.
*
*/
%%
==Special Phrases==
Special expressions are words with an '@' at the beginning. The following could be used:
@package
@subpackage
@name
@author
@license
@copyright
@version
@input
@output
@uses
@todo
==Links==
//follows//
==Template for Actions==
//not finished//
%%(php)
<?
/**
* The first sentence should descripe the action and must end with a dot.
*
* Here follows the long version of the description.
*
* Another part of the description.
*
* @package Action
* @subpackage //choose one
* @name //the name of this action
*
* @author
* @license
* @copyright
* @version
*
* @input
* @output
*
* @uses
* @todo
*/
%%
