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.

MIRA_ADD_DOCUMENTATION(TargetName
    DIRS
        doc
        include
        src
    DEPENDS
        otherPackage
)

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

///@endcond

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
{

};

///@endcond

How to add code examples

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

/**
\code
MyClass class;
class.callThisFunction();
...
\endcode
*/

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.