Development guide

Documentation

In order to keep project documentation and source code in sync, reference documentation is automatically generated from the source code. For this to work, the documentation for classes, functions, types, etcetera have to follow certain conventions. These are described in the following sub-sections.

General conventions

Documentation that is to be included in the automatically generated reference documentation uses the JavaDoc style, which consists of a C-style comment block starting with two *'s like this:

/**
 * ... text ...
 */

Brief documentation (single line) that is to be included in the automatically generated reference documentation uses the C++ style comments with one additional slash.

/// Brief description
/**
 * Detailed description
 */

The documentation is always written before the item to be documented. In the case of a class or function declaration/definition, the documentation is written immediately before the return type. Also for classes and functions, the documentation comment is indented one step deeper than the declaration.

By putting a number of column-aligned minus signs at the start if a line, a bullet list will be generated. Numbered items lists can also be generated by using a minus sign followed by a hash. Nesting of lists is allowed and is based on indentation of the items.

Paragraphs can be separated by inserting an empty documentation line.

Classes and structs

The documentation for a class or struct is written before the "class" keyword.

/**
 *  This class implements a thread-based timer.
 * 
 *  A timer starts a thread that first waits for a given start
 *  interval.
 *  Once that interval expires, the timer callback is called
 *  repeatedly in the given periodic interval.
 *  If the interval is 0, the timer is only
 *  called once.
 *  The timer callback method can stop the timer by setting the
 *  timer's periodic interval to 0.
 * 
 *  The timer callback runs in its own thread, so multithreading
 *  issues (proper synchronization) have to be considered when
 *  writing the callback method.
 * 
 *  The exact interval at which the callback is called depends on
 *  many factors like operating system, CPU performance and system
 *  load and may differ from the specified interval.
 * 
 *  The timer thread is taken from the global default thread pool, so
 *  there is a limit to the number of available concurrent timers.
 */
class Foundation_API Timer: protected Runnable
{
public:
...
};

Functions

The documentation for a function is written directly before the function declaration.

The parameters of a function are not documented separately. However, if a parameter requires special attention, a brief sentence or paragraph about it is written in the function documentation.

If the function may throw an exception, a paragraph should be written that describes which exceptions may be thrown under what circumstances.

If the function returns a value, the value should be described in a short paragraph.

/**
 * Starts the timer.
 *  Create the TimerCallback as follows:
 *  TimerCallback<MyClass> callback(*this, &MyClass::onTimer);
 *  timer.start(callback);
 */
void start(const AbstractTimerCallback& method);
/**
 * Returns the index'th token.
 *  Throws a RangeException if the index is out of range.
 */
const std::string& operator [] (int index) const;
/**
 * Unloads the given library.
 * 
 *  Be extremely cautious when unloading shared libraries.
 *  If objects from the library are still referenced somewhere,
 *  a total crash is very likely.
 * 
 *  If the library exports a function “pocoUninitializeLibrary”,
 *  this function is executed before it is unloaded.
 * 
 *  If loadLibrary() has been called multiple times for the same
 *  library, the number of calls to unloadLibrary() must be the
 *  same for the library to become unloaded.
 */
void unloadLibrary(const std::string& path)
{
    FastMutex::ScopedLock lock(_mutex);
    typename LibraryMap::iterator it = _map.find(path);
    ...
}

Enumerations

The documentation for an enumeration is written directly before the enum keyword. The documentation for each enumeration value is written directly after each value.

/// Flags that modify the matching behavior.
enum Options
{
    GLOB_DEFAULT = 0x00, /// default behavior
    GLOB_DOT_SPECIAL = 0x01, /// '*' and '?' do not match '.' at beginning of subject
    GLOB_DIRS_ONLY = 0x80 /// only glob for directories
};

Types

Documentation for at type definition is written directly before the typedef statement.

/// UTC time value in microsecond resolution
typedef Int64 TimeVal; 

TODO lists

Open issues in the code should be clearly marked with a TODO item inside the documentation. A TODO item should start with \todo followed by a paragraph where the TODO item is described. Doxygen will clearly mark them inside the auto-generated documentation. It will also add these items to a separate TODO list. The two instances of the description will be cross-referenced.

/**
 * \todo Add documentation to this function...
 * \todo This function is not stable. Fix it!
 */