| -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__.
|
| +__current APIDocumentation is in pdpDocumentor format, the same as used for Smarty itself - these notes will be brought in line once work is complete !__ |
|
|
| -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.
|
| +In an effort to document our code, we've started using code comments and [http://www.stack.nl/~dimitri/doxygen/|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__. |
| + |
| +{maketoc} |
| +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
|
| -{CODE()}/**
|
| -* $Header: /cvsroot/tikipro/_p_tp_kernel/cache_lib.php,v 1.1.2.3 2004/07/01 12:57:15 wolff_borg Exp $
|
| +{CODE source=php}/** |
| +* $Header: /cvsroot/bitweaver/_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) 2004 bitweaver.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.
|
| +*/{/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 bitweaver CVS source tree. |
|
|
| !!Class Description
|
| -{CODE()}/**
|
| +{CODE source=php}/** |
| * 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 $
|
| +* @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 $ |
| +* |
| * @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
|
| +...}{/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]. |
|
|
| -!Generated Lists
|
| +!!!@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|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.
|
| +!!!@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|Doxygen documentation for __\deprecated__]
|
| +!!!@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|Doxygen documentation for __\bug__]
|
| +!!!@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|Doxygen documentation for __\test__]
|
| +!!!@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 source=php} /** |
| + * 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 source=php} /** |
| + * 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... |