History of APIDocumentation

In an effort to document our code, we've started using code comments and Doxygen (http://www.stack.nl/~dimitri/doxygen/). To browse the API documentation, visit http://your.tikipro.install/doc/html/.
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.
• @date created 2003/11/25
• @author lrargerich <lrargerich@yahoo.com>
• @version $Revision: 1.1.2.4 $ $Date: 2004/07/03 02:21:19 $ $Author: wolff_borg $
• @package Kernel
• @class Cachelib
• @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 if possible point to a code example if its difficult to use.

Doxygen Commands

The next section is a list of fields recognised by Doxygen. For the full listing of Doxygen commands, see http://www.stack.nl/~dimitri/doxygen/commands.html.

@date

http://www.stack.nl/~dimitri/doxygen/commands.html#cmddate
We use date to indicate when the file or library was first created. The date format yyyy/mm/dd is used to standardise with CVS $Date:$ field.

@author

http://www.stack.nl/~dimitri/doxygen/commands.html#cmdauthor
Authors of the file or library are listed here. This command ends with a blank line. Usually CVS name and email address are included.

@version

http://www.stack.nl/~dimitri/doxygen/commands.html#cmdversion
For this we use CVS dynamic fields $Revision: ... $ $Date: ... $ $Author: ... $. This ensure the data is always up to date and maintenance free.
We don't use CVS $Name: xxx $ as they do not work well with CVS merges.

@package

http://www.stack.nl/~dimitri/doxygen/commands.html#cmdpackage
We try and group libraries into packages for classification, but this still needs work.

@class

http://www.stack.nl/~dimitri/doxygen/commands.html#cmdclass
This identifies the code as a class to Doxygen which is then used to create graphical inheritence and the like.

Generated Lists

The following are tags that will help our coding efforts.

@todo

http://www.stack.nl/~dimitri/doxygen/commands.html#cmdtodo
This tag is used for something still pending to do. Please don't use FIXME as it does not work with Doxygen. Use @todo to ensure it makes it to the generated list. This command ends with a blank line. The todo command will associate itself to the previous command, so be careful with its placement.

@deprecated

http://www.stack.nl/~dimitri/doxygen/commands.html#cmddeprecated
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
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
Used to describe a test case - not really sure how we would use this yet.

Variable Description

{CODE()} /**

• Used to store the directory used to store the cache files.
• /

var $_folder;{CODE}
For variable, just include a line to explain its use.

Function Description

{CODE()} /**

• Used to retrieve an object if cached.
• @param key the unique identifier used to retrieve the cached item
• @return object if cached object exists
• /

function getCached($key)
{{CODE}

@param

http://www.stack.nl/~dimitri/doxygen/commands.html#cmdparam
Used in the following way @param parameter_name description, identify each parameter and give a quick description of its use.

@return

http://www.stack.nl/~dimitri/doxygen/commands.html#cmdreturn
Used in the following way @return object_type description, identifies the return object type and give a quick description of what information is returned.

Doxygen Settings

Explain why we use the settings we do...

current APIDocumentation is in pdpDocumentor format, the same as used for Smarty itself - these notes will be brought in line once work is complete !

In an effort to document our code, we've started using code comments and Doxygen (http://www.stack.nl/~dimitri/doxygen/). To browse the API documentation, visit http://your.bitweaver.install/doc/html/.
The Doxygen config file can be found under yourbitweaverinstall/doc/doxygen.cfg.

This page is to help new (and old) bitweaver 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

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 bitweaver CVS source tree.

Class Description

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 if possible point to a code example if its difficult to use.

Doxygen Commands

The next section is a list of fields recognised by Doxygen. For the full listing of Doxygen commands, see http://www.stack.nl/~dimitri/doxygen/commands.html.

@date

http://www.stack.nl/~dimitri/doxygen/commands.html#cmddate
We use date to indicate when the file or library was first created. The date format yyyy/mm/dd is used to standardise with CVS $Date:$ field.

@author

http://www.stack.nl/~dimitri/doxygen/commands.html#cmdauthor
Authors of the file or library are listed here. This command ends with a blank line. Usually CVS name and email address are included.

@version

http://www.stack.nl/~dimitri/doxygen/commands.html#cmdversion
For this we use CVS dynamic fields $Revision: ... $ $Date: ... $ $Author: ... $. This ensure the data is always up to date and maintenance free.
We don't use CVS $Name: xxx $ as they do not work well with CVS merges.

@class

http://www.stack.nl/~dimitri/doxygen/commands.html#cmdclass
This identifies the code as a class to Doxygen which is then used to create graphical inheritence and the like.

Generated Lists

The following are tags that will help our coding efforts.

@todo

http://www.stack.nl/~dimitri/doxygen/commands.html#cmdtodo
This tag is used for something still pending to do. Please don't use FIXME as it does not work with Doxygen. Use @todo to ensure it makes it to the generated list. This command ends with a blank line. The todo command will associate itself to the previous command, so be careful with its placement.

@deprecated

http://www.stack.nl/~dimitri/doxygen/commands.html#cmddeprecated
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
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
Used to describe a test case - not really sure how we would use this yet.

Variable Description

For variable, just include a line to explain its use.

Function Description

@param

http://www.stack.nl/~dimitri/doxygen/commands.html#cmdparam
Used in the following way @param parameter_name description, identify each parameter and give a quick description of its use.

@return

http://www.stack.nl/~dimitri/doxygen/commands.html#cmdreturn
Used in the following way @return object_type description, identifies the return object type and give a quick description of what information is returned.

Doxygen Settings

Explain why we use the settings we do...