History of APIDocumentation
Version 18 | Current version | |
---|---|---|
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 CommentsBelow are some examples of code comments. Please use them as templates - and any improvements should be posted back here.Copyright Notice{CODE()}/**
Class Description{CODE()}/**
{ ...{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 CommandsThe 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.@datehttp://www.stack.nl/~dimitri/doxygen/commands.html#cmddateWe 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. @authorhttp://www.stack.nl/~dimitri/doxygen/commands.html#cmdauthorAuthors of the file or library are listed here. This command ends with a blank line. Usually CVS name and email address are included. @versionhttp://www.stack.nl/~dimitri/doxygen/commands.html#cmdversionFor 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. @classhttp://www.stack.nl/~dimitri/doxygen/commands.html#cmdclassThis identifies the code as a class to Doxygen which is then used to create graphical inheritence and the like. Generated ListsThe following are tags that will help our coding efforts.@todohttp://www.stack.nl/~dimitri/doxygen/commands.html#cmdtodoThis 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. @deprecatedhttp://www.stack.nl/~dimitri/doxygen/commands.html#cmddeprecatedDeperecate 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. @bughttp://www.stack.nl/~dimitri/doxygen/commands.html#cmdbugIndicates where one or more bugs have been reported - is wise to reference a SourceForge bug number. @testhttp://www.stack.nl/~dimitri/doxygen/commands.html#cmdtestUsed to describe a test case - not really sure how we would use this yet. Variable Description{CODE()} /**
For variable, just include a line to explain its use. Function Description{CODE()} /**
{{CODE} @paramhttp://www.stack.nl/~dimitri/doxygen/commands.html#cmdparamUsed in the following way @param parameter_name description, identify each parameter and give a quick description of its use. @returnhttp://www.stack.nl/~dimitri/doxygen/commands.html#cmdreturnUsed in the following way @return object_type description, identifies the return object type and give a quick description of what information is returned. Doxygen SettingsExplain why we use the settings we do...</lrargerich> | 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 CommentsBelow 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 CommandsThe 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.@datehttp://www.stack.nl/~dimitri/doxygen/commands.html#cmddateWe 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. @authorhttp://www.stack.nl/~dimitri/doxygen/commands.html#cmdauthorAuthors of the file or library are listed here. This command ends with a blank line. Usually CVS name and email address are included. @versionhttp://www.stack.nl/~dimitri/doxygen/commands.html#cmdversionFor 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. @classhttp://www.stack.nl/~dimitri/doxygen/commands.html#cmdclassThis identifies the code as a class to Doxygen which is then used to create graphical inheritence and the like. Generated ListsThe following are tags that will help our coding efforts.@todohttp://www.stack.nl/~dimitri/doxygen/commands.html#cmdtodoThis 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. @deprecatedhttp://www.stack.nl/~dimitri/doxygen/commands.html#cmddeprecatedDeperecate 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. @bughttp://www.stack.nl/~dimitri/doxygen/commands.html#cmdbugIndicates where one or more bugs have been reported - is wise to reference a SourceForge bug number. @testhttp://www.stack.nl/~dimitri/doxygen/commands.html#cmdtestUsed 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
@paramhttp://www.stack.nl/~dimitri/doxygen/commands.html#cmdparamUsed in the following way @param parameter_name description, identify each parameter and give a quick description of its use. @returnhttp://www.stack.nl/~dimitri/doxygen/commands.html#cmdreturnUsed in the following way @return object_type description, identifies the return object type and give a quick description of what information is returned. Doxygen SettingsExplain why we use the settings we do... |