History of APIDocumentation
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/bitweaver/_p_tp_kernel/cache_lib.php,v 1.1.2.3 2004/07/01 12:57:15 wolff_borg Exp $
*
* 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 bitweaver 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 $
*
* @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.__
!!!@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...
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/bitweaver/_p_tp_kernel/cache_lib.php,v 1.1.2.3 2004/07/01 12:57:15 wolff_borg Exp $
*
* 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 bitweaver 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 $
*
* @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.__
!!!@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...