All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Documenting Your Code

Documentation of a domain or toolbox package

To document your package, add a folder named doc to your package. Then add a file with the ending .dox in the directory doc and put the following into that file.

\mainpage Domain MyDomain - Documentation
\author Your Name
\section FirstSection

Bla, bla...

\li A list item

Then add the following CMake macro to your CMakeLists.txt.


TargetName must be an arbitrary target name. Under DIR add all directories that you want doxygen to search for files to parse. Under DEPENDS add targets of other domains/toolboxes that have also been added with the MIRA_ADD_DOCUMENTATION macro, if you use types of them and want doxygen to automatically add links to their documentation.

Unit documentation

When documenting your unit, please use the following structure:

\section Units

\subsection MyUnit1

\subsubsection Channels

\paragraph Published
- \channel{Channel1,std::string}
  Documentation of channel content

\paragraph Subscribed
- \channel{Channel2,std::string}

\subsubsection Parameters
- \member{MemberName, std::string}
  Documentation of member.
- \property{PropertyName, std::string}
  Documentation of property.

\subsubsection Transforms
- \transf{SomeTransform}
  Documentation of the transform.

\subsubsection Services

\paragraph Required
- \service{RequiredService1}

\paragraph Published
- \service{PublishedService1}

Note that in the code above some convenience aliases are used for documenting channels, members and properties, transforms and services.

Insource documentation with Doxygen

How to document your class

Put a comment in the following format before your class:

 * This first sentence is used as brief comment for my class.
 * These sentences are displayed in the detailed section of the documentation.
class MyClass


Please note, that the first sentence is automatically used as brief documentation.

How to document your method

Put a comment in the following format before your method:

 * This sentences are used to describe the function of your method.
 * @param[out] oParam  The output value
 * @param[in]  iParam1 Some input value
 * @param[in]  iParam2 Another input value
 * @return             The return value
bool myMethod(int& oParam, const int iParam1, const ComplexClass& iParam2);

Please note, that the "[out]" and "[in]" specification for the parameters is optional. The parameter description in general is not mandatory.

How to exclude certain parts of your code from the documentation

Put the following comment

///@cond INTERNAL

before the code section you want to exclude and the following comment


after your code section. Example:

///@cond INTERNAL

 * A class that is used internally only and should not be included into the
 * public documentation.
class MyPrivateClass



How to add code examples

To add code examples (e.g. usage of a class) to your documentation use the following lines:

MyClass class;

How to group classes to a module

Create a file "YourModulesName.dox" in the include path of your module and add the following lines to that file:

@defgroup YourModulesName My Module

// this is optional:
@ingroup ModuleYourModuleBelongsTo

In this file you can also add additional detailed information that are shown under "related pages", see How to add detailed information in related pages.

To add a class to your module just add

@ingroup YourModulesName

to the documentation of your class, function, macro, etc.

If you don't need an extra file for your module's documentation you can also add the

@defgroup YourModulesName My Module

command to any of your classes. However, make sure that it is added to one class only.

How to add detailed information in related pages

Create a file "YourModulesName.dox" in the include path of your module and add the following lines to that file:

\page MyRelatedPage This is My Related Page

Add all the documentation here


You can also add a module definition to that file, see How to group classes to a module.