In an effort to document our code, we've started using code comments and 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

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

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

Doxygen documentation for \bug
Indicates where one or more bugs have been reported - is wise to reference a SourceForge bug number.

\test

Doxygen documentation for \test
Used to describe a test case - not really sure how we would use this yet.