More about ELESOFTROM Company

ELESOFTROM Company is specializing in firmware development and fixing for embedded systems.

We have more than 10-years of experience in that area.

In developed tasks and projects we value reliability and effectivness of the firmware.

Fixing the Software for Emebedded Systems

Software for Microcontrollers

Home page

Full offer


About company


DioneOS - RTOS for embedded devices

ELESOFTROM developed RTOS for ARM Cortex-M3 and msp430.

The system is optimized for short execution time, having short switching time between threads.
The system provides elements (e.g. semaphores, mutexes, timers, queues etc.) used for building multi-threaded firmware.

Cortex version has full tests coverage and was tested by automatic testing framework.

Read more:

DioneOS home page



DioneOS documentation

Tutorials about DioneOS

Documenting Source Code

2012-05-12    Piotr Romaniuk, Ph.D.


Doxygen - the Tool for Building Documentation,
Doxygen Syntax of Description in the Code,
Configuration a Doxygen Project (doxywizard).
Customizing Documentation Look
Links (Doxygen documentation)

Even good source code without documentation is difficult to maintain. Missing or partial documentation is painful, when other team programmers are trying to modify or use existing code. As the result, extra time and work is needed just for understand how it works and how to use it. The problem is also concerns the author of the code, because after some time (e.g. a few months) he forget details of his own implementation. Because of that, the best time to make documentation is the moment of creating source code. Of cource, it is difficult for programmer to write or update separated description in doc files (.doc, .pdf, etc.), especially when different programs must be used for the editing.
The solution for the problem is universal tool that extracts an information from source files and builds documentation on that basis. The programmer during writing the program in source form, without leaving the editor, can embed description of the code. Next, properly configured tool is run, extracts the descriptions and makes organized form od documentation in HTML or LaTeX.

Doxygen - the Tool for Builing Documentation
Good example of the tool for building documentation from source files is
Doxygen. The information is written in comments blocks, so it is not visible for compilation process. Following part of description is devoted to C language sources, nevertheless Doxygen can handle other languages, like: C++, C#, Java, PHP, Fortran, VHDL. In a case of C language, comments are removed by C preprocessor before compilation.
For example, implementation of some function can be described in the source file by:

/** @brief Waits on the semaphore with timeout
* Calling this may cause context switch.
* @warning Do not call it when preemption is disabled - it will not block or throw os_bug
* @note may throw os_bug if os_ready_threads is empty, or when semaphore counter overflows \n
* Timeout may be shorter than specified in argument list by 1 unit or longer, depending on latencies in the system.
* @param[in] sem the pointer to the semaphore structure
* @param[in] timeout waiting timeout in os_tick units
* @return #OS_STATUS_OK when success \n
* #OS_PREEMPT_DIS when preemption is disabled and check this issue is disabled in config.h \n
* #OS_TIMEOUT when timeout has expired, note that semaphore could be released between timeout has elapsed
* and function returned. If it is important, in this case call os_sema_tryget(), but after you cannot
* obtain semaphore the release may happen so this looks again like uncertainty in return from the function.

os_result_t os_sema_wait_timeouted( os_sema_t * sem, unsigned short timeout );

The above part results in following part of documentation:

Example of documention generated from description in source code
(from documentation of DioneOS system).

It can be noticed that minimal description in the file, but containing all necessary information, has been transformed into well-looking, convenient to use and clear form, in a form of HTML pages, that can be easily browsed by web browser. Besides the contents, multiple links have been created to make the documentation easier to browse and useful (e.g. definition OS_STATUS_OK, definition of type os_sema_t). Doxygen build also the indexes and lists of items: source files, structures, data types, macrodefinitions, etc. The web page interface provides a search function if someone needs to find specific name. It is possible to add extra pages in HTML that extends description (they are grouped in Related Pages section).

View of whole documentation page, if you want to see how works examplar documentation click on above image or here.
Notice added links to another sites (site of DioneOS and home page of ELESOFTROM Company)
located on the top and bottom of the page. You can see custom header and footer in HTML.

Doxygen Syntax of Descriptions in Source Code

Sections for Doxygen begins from a sequence '/**' and ends by '*/', because they are embedded in the comments block, they are not visible for compilation and ignored. At the same time, Doxygen can easily extract it.
All Doxygen keywords starts from @ character, and references to another items begins from #. Below the syntax for description basic elements in sources is presented together with some examples.

Description of source file

@file - specifying name of the file,
@anchor - 'anchor' name used for refering in different locations by creating links,
@brief - short description of the contents,
@author - author of the file ,
@version - version of the file.


/** @file semaphore.h
* @anchor sema
* @brief Semaphores
* @author Piotr Romaniuk, (c) ELESOFTROM
* @version 1.0 Feb 4, 2011
* A semaphore is one of synchronization object, it provides well-known mechanism for signalling
* between threads. The semaphore contains an internal counter initialized with a number

Function Description

Funcion description should be written before the definition/declaration of the function and contain following items:

@brief - short description of the function (the end of this description is marked by empty line),
    further description (after the empty line) is considered to be extended one.
@param[ in | out | in/out ] - enumeration of function parameters (Note: between the name and meaning fields do not use dash character),
    in square bracket type of argument should be specified: input, output or both of them.
@return - description of the value returned by the function.


/** @brief Try to obtain semaphore
* The function tries to obtain semaphore but never blocks (waits) on it.
* The result of operation is returned by return code.
* @param[in] sem pointer to the semaphore structure
* @return #OS_STATUS_OK when semaphore has been obtained\n
* #OS_WOULD_WAIT if semaphore is busy and trial of waiting on it would block

os_result_t os_sema_tryget( os_sema_t * sem );

In the above example are two references to other items: OS_STATUS_OK and OS_WOULD_WAIT, described elsewhere. Correct syntax requires # character in reference.

Description of the Structural Type

General description should be before its declaration, but field description can be put as a line continuation of described structure items. (please note a sequence of character /**<, especially 'less' character) .

@brief - short description of structure or field,

/**@brief data type for state machine description */

struct os_state_machine_s{

os_list1_t list_chain;

/**<brief field for chaining in state machine manager on active state machines list*/

os_sm_handler_t *handlers;

/**<brief table of pointers to functions that handle events (handlers) in each state*/

int state;

/**<@brief current state */

int states_nb;

/**<@brief number of states*/

os_ring_buffer_ev_t ev_queue;

/**<@brief queue that stores incomming events */

void * xdata;

/**<@brief extra data for user */


Description of Macrodefinition

Depending on macrodefinition type, its description can be put before or continue the line of the macro.

Example 1.

define OS_WAIT_INFINITE 0 /**<@brief symbol for infinite wait on semaphore */

Example 2.

/** @brief Macro releases the semaphore.
* @note Use it only in ISR.\n
* @note may throw os_bug if semaphore counter overflows.
* @param[in] sem the pointer to the semaphore structure
* @return always returns #OS_STATUS_OK

#define os_sema_post_intr( sem ) os_sema_post_common( sem , 1 )

Description of Enumerated Type (enum)


/** @brief Thread state.
* The values for thread state description.
enum os_thread_state_e{
OS_THREAD_WAIT = 1, /**<@brief Thread is waiting on some waiting object. It cannot be scheduled */
OS_THREAD_READY = 2,/**<@brief Thread is ready to be scheduled, but now higher priority thread is running */
OS_THREAD_RUNNING = 3/**<@brief Thread is running, its context is current */

Other useful keywords

@anchor - defines 'anchor', that can be refered from other location by prefixing the name with # character.
@warning - warning in documention,
@note - a note in documentation,
@todo - item to be implemented (unfinished, not implemented yet),
@bug - a bug description (not solved yet),
@deprecated - marking items that will be removed in future versions and using it should be avoided, but left for compatibility with older versions for now.
Doxygen can create separated page with bugs, warnings and todo items from the source code.
@code / @endcode - defines a section in description formatted as a source code,
In Doxygen sections it is allowed to put HTML characters, e.g. <br>, <b> </b>,
and embed images, like in HTML, by <img src="file-name">
@addtogroup / @{ / @} / @defgroup - group definition (they are some kind of modules consisting multiple source files),
@mainpage / @page / @subpage - creating separeted pages included into documentation.

Configuration a Doxygen Project (doxywizard)

Although Doxygen project can be configured in text editor, useful tool can be used for this purpose - i.e. Doxywizard. Programmer should point out location of source files, that will be processed, should specify output folder and many options that controls level of details and look of documentation. It is also possible to define preprocessor symbol, that will be interpreted during the process of building the documentation. This feature helps to control conditional excluding parts of code that will be used only for compilation but hidden for Doxygen, so they do not appear in documentation.

Look of the interface for configuration options of the Doxygen project, in left panel
context help can be visible (after moving the mouse over the option to be explained)

Doxygen provides also an option to inlude all source code into documentation with active links directing to corresponding description.

Example of part of documentation with source code,
lines with highlighted number in blue (e.g. 00017, 00024)
are links to description of defined item.

Customizing Documentation Look

Doxygen provides a way for customizing a look of documentation, it is possible by specification following items:

  • log file,
  • user interface colors,
  • documentation format (single HTML file, or frame based format with multiple files)
  • which items will be put into documentation (presence of search function, index, lists, etc.),
  • using custon header and footer in HTML, that will be part of documentation files in HTML (they will be included at the begining and at the end of created documentation files - they form some kind of envelope),
  • custom styles CSS - an option for control colors, fonts, etc.

The process of documentation building can be extended by a set of simple scripts, that converts created HTML files into PHP format. This can add some extra functions or contents protection features (e.g. login page and user registration or dynamically added contents).


On-line Doxygen documentation (after doxygen installation it is also localy available)
List of keywords used as directives for Doxygen