login | register
Sat 20 of Mar, 2010 (20:42 UTC)

bitweaver - Web Application Framework and CMS

Web Application Framework and CMS

Technical_Documentation » Developer_Guide » CodingGuidelines » APIDocumentation
« TestingSuitesTutorials »
Refresh cacheHistoryPrint

APIDocumentation

Created by: Stephan Borg, Last modification: Sat 11 of Mar, 2006 (11:59 UTC) by Uwe Zimmermann
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.

Page Contents

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

/**
* $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 $
*/

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

/**
* 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
{
...}

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

    /**
    * Used to store the directory used to store the cache files.
    */
    var $_folder;

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

Function Description

    /**
    * 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)
    {...
    }


@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...

Related Items

Documentation » Technical Documentation

Documentation geared towards developers and people who want to learn about the core processes of bitweaver

HEAD ON! Support has been added for Pear::DB!  •  Oracle Reservations for Two  •  ReleaseTwo: Shedding that last bits of our roots, finding the core of our being  •  getContentList  •  How to add a pagination to an object list  •  Moving bw in another directory  •  safe mode on / open_base_dir  •  sequence and auto  •  Anatomy of a Package  •  APIDocumentation  •  Archived Picture Upload with Fisheye under Windows  •  Bitweaver and Browser Cookies  •  bitweaverCVS  •  bitweaverPerformance  •  Contribute Code  •  CreatingServices  •  CssSchema  •  Divs vs Tables  •  InstallbitweaverDoc  •  IntegrationTutorial  •  LibertyFormats  •  LibertyMime  •  LibertyServices  •  MySQL and character encoding  •  phpdoc content status  •  PortingTikiWikiPackages  •  PrototypeAjaxObject  •  PrototypeReference  •  SamplePackage  •  SearchPackageDevNotes  •  TUTORIAL - Displaying Icons ONLY to AUTHORS of the page  •  Tutorial - Liberty Plugins  •  Tutorial - Liberty Plugins II  •  UsersDoc

Comments