Cpp

File structure of a package

include
|-- example_header.h
|-- another_example.h
src
|-- main.cpp
|-- example_file.cpp
CMakeLists.txt
package.xml
README.md

Documentation

We require that three pieces of documentation are provided for every package:

1. A readme following the recommendations from the Github section
2. A docstring at the top of every header file
3. A docstring for every function and class

Note that all the docstrings should be written in the header (.h) files. Any helper functions in the source files do not need to follow the same style of documentation. The documentation style must follow the Doxygen guidelines. Below you will find an example of how this can be done.

Doxygen

As highlighted in the example below, the most important commands to include are:

1. File: Without the file command, your file will not be included when the documentation is generated
2. Brief: Every file, function, class, struct etc. should have a brief containing the most important information about it
3. Param: Every parameter that a function takes should be given a short explanation.
4. Return: The return values of functions should be explained

/**
 * @file
 * @brief A brief description of this file
 * A more detailed description of this file.
*/

/**
 * @brief An example class.
 * A more elaborate class description.
*/
class example_class {​​​​

public:

 /**
  * @brief An enum.
  * More detailed enum description.
 */
 enum example_enum {​​​​
     val1, /**< enum value val1. */
     val2, /**< enum value val2. */
     val3  /**< enum value val3. */
 }​​​​
 *enum_ptr, /**< enum pointer. Details. */
  enum_var; /**< enum variable. Details. */


 /**
  * @brief A constructor.
  * 
  * A more elaborate description of the constructor.
 */
 example_class();


 /**
  * @brief a normal member taking two arguments and returning an integer value.
  * 
  * @param test_param       an integer argument.
  * @param another_param    a constant character pointer.
  * 
  * @see example_class()
  * @see public_var()
  * 
  * @return an integer containing the test results
  * 
  * @warning this is a warning
 */
 int test_me(int test_param, const char *another_param);


 /**
  * @brief a variable.
  * A more thorough description of a variable.
 */
 int var1; 

 int var2; /** A simple description of a variable*/
}​​​​;

If you are more interested in the capabilities of Doxygen, feel free to read through the manual. Warning: The manual contains a lot of in-depth information - much more than what we require.