2012-05-12 Piotr Romaniuk, Ph.D.
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).
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.
Example
/** @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.
Example
/** @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,
Example:
/**@brief data type for state machine description */
Depending on macrodefinition type, its description can be put before or continue the line of the macro.
Example 1.
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
*/
/** @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 */
};
@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.
