History of APIDocumentation
In an effort to document our code, we've started using code comments and [http://www.stack.nl/~dimitri/doxygen/|Doxygen]. The Doxygen config file can be found under ''yourtikiproinstall''__/doc/doxygen.cfg__.
This page is to help new (and old) Tikipro developers understand how and why we do things the way we do - for API documentation anyway.
!Class Doc Comments
Below are some examples of code comments. Please use them as templates - and any improvements should be posted back here.
!!Copyright Notice
{CODE()}/**
* $Header: /cvsroot/tikipro/_p_tp_kernel/cache_lib.php,v 1.1.2.3 2004/07/01 12:57:15 wolff_borg Exp $
*
* Copyright (c) 2004 tikipro.org
* Copyright (c) 2003 tikwiki.org
* Copyright (c) 2002-2003, Luis Argerich, Garland Foster, Eduardo Polidor, et. al.
* All Rights Reserved. See copyright.txt for details and a complete list of authors.
* Licensed under the GNU LESSER GENERAL PUBLIC LICENSE. See license.txt for details
*
* $Id: cache_lib.php,v 1.1.2.3 2004/07/01 12:57:15 wolff_borg Exp $
*/{CODE}
This is our copyright notice. Everything with a __$__ tag eg ''$Header: ... $'' is dynamically updated by CVS. This should be included at the beginning of every file in the Tikipro CVS source tree.
!!Class Description
{CODE()}/**
* A basic library to handle caching of some Tiki Objects. Usage is simple and feel free to improve it.
*
* Currently used to cache user permissions only. Could be used to store blobs to files and other static
* database intensive queries.
* @example kernel/setup_inc.php
* @example users/users_lib.php
*
* @date Created $Date: 2003/11/25 12:57:15 $
* @author lrargerich <lrargerich@yahoo.com>
* @date Modified $Date: 2004/07/01 12:57:15 $
* @author Last $Author: wolff_borg $
* @version $Revision: 1.1.2.3 $
* @class Cachelib
* @package kernel
* @todo Need to implement in more places
*/
class Cachelib
{
...{CODE}
So quick explanation. The first two paragraphs are just a description of the class and what it does. Its wise to included where it is used, and possible a code example if its difficult.
* @abstract
!Generated Lists
The following are tags that will help our coding efforts.
!!\todo
[http://www.stack.nl/~dimitri/doxygen/commands.html#cmdtodo|Doxygen documentation for __\todo__]
This tag is used for something still pending to do. __FIXME__ is a similar tag, but does not work with Doxygen. Please don't use FIXME or TODO - rather use __\todo__ to ensure it makes it to the generated list.
!!\deprecated
[http://www.stack.nl/~dimitri/doxygen/commands.html#cmddeprecated|Doxygen documentation for __\deprecated__]
Deperecate code is to be phased out. Use this to indicate when you plan to phase it out and alternative classed or functions that it has been replaced by.
!!\bug
[http://www.stack.nl/~dimitri/doxygen/commands.html#cmdbug|Doxygen documentation for __\bug__]
Indicates where one or more bugs have been reported - is wise to reference a SourceForge bug number.
!!\test
[http://www.stack.nl/~dimitri/doxygen/commands.html#cmdtest|Doxygen documentation for __\test__]
Used to describe a test case - not really sure how we would use this yet.
This page is to help new (and old) Tikipro developers understand how and why we do things the way we do - for API documentation anyway.
!Class Doc Comments
Below are some examples of code comments. Please use them as templates - and any improvements should be posted back here.
!!Copyright Notice
{CODE()}/**
* $Header: /cvsroot/tikipro/_p_tp_kernel/cache_lib.php,v 1.1.2.3 2004/07/01 12:57:15 wolff_borg Exp $
*
* Copyright (c) 2004 tikipro.org
* Copyright (c) 2003 tikwiki.org
* Copyright (c) 2002-2003, Luis Argerich, Garland Foster, Eduardo Polidor, et. al.
* All Rights Reserved. See copyright.txt for details and a complete list of authors.
* Licensed under the GNU LESSER GENERAL PUBLIC LICENSE. See license.txt for details
*
* $Id: cache_lib.php,v 1.1.2.3 2004/07/01 12:57:15 wolff_borg Exp $
*/{CODE}
This is our copyright notice. Everything with a __$__ tag eg ''$Header: ... $'' is dynamically updated by CVS. This should be included at the beginning of every file in the Tikipro CVS source tree.
!!Class Description
{CODE()}/**
* A basic library to handle caching of some Tiki Objects. Usage is simple and feel free to improve it.
*
* Currently used to cache user permissions only. Could be used to store blobs to files and other static
* database intensive queries.
* @example kernel/setup_inc.php
* @example users/users_lib.php
*
* @date Created $Date: 2003/11/25 12:57:15 $
* @author lrargerich <lrargerich@yahoo.com>
* @date Modified $Date: 2004/07/01 12:57:15 $
* @author Last $Author: wolff_borg $
* @version $Revision: 1.1.2.3 $
* @class Cachelib
* @package kernel
* @todo Need to implement in more places
*/
class Cachelib
{
...{CODE}
So quick explanation. The first two paragraphs are just a description of the class and what it does. Its wise to included where it is used, and possible a code example if its difficult.
* @abstract
!Generated Lists
The following are tags that will help our coding efforts.
!!\todo
[http://www.stack.nl/~dimitri/doxygen/commands.html#cmdtodo|Doxygen documentation for __\todo__]
This tag is used for something still pending to do. __FIXME__ is a similar tag, but does not work with Doxygen. Please don't use FIXME or TODO - rather use __\todo__ to ensure it makes it to the generated list.
!!\deprecated
[http://www.stack.nl/~dimitri/doxygen/commands.html#cmddeprecated|Doxygen documentation for __\deprecated__]
Deperecate code is to be phased out. Use this to indicate when you plan to phase it out and alternative classed or functions that it has been replaced by.
!!\bug
[http://www.stack.nl/~dimitri/doxygen/commands.html#cmdbug|Doxygen documentation for __\bug__]
Indicates where one or more bugs have been reported - is wise to reference a SourceForge bug number.
!!\test
[http://www.stack.nl/~dimitri/doxygen/commands.html#cmdtest|Doxygen documentation for __\test__]
Used to describe a test case - not really sure how we would use this yet.