Comment the Code

This section requires embedXcode+.

The second step consists on adding specific comments with defined keywords right into the code.

The comments for self-documentation start with /// instead of the standard // and include keywords with a @ prefix.

///
/// @mainpage   embed1
///
/// @details    Description of the project
/// @n

This means that standard comments starting with the standard // aren't included in the documentation.

Doxygen includes many more options.

Comment a Function

Use the Doxygen Helper to speed up and ease the writing of comments for the functions.

  • Just select the code of a function.

  • Either press Cmd+Shift+D,

  • Or call the menu Xcode > Services > Doxygenise.

The helper generates a template for the comment lines.

  • Use the tab key to replace the light-blue fields with the comments.

In this example, the comments include the @brief description of the function, list all the @parameters as well as the @returned value.

///
/// @brief      Blink a LED
/// @details    LED attached to pin is turned on then off
/// @note       Total cycle duration = ms
/// @param      pin pin to which the LED is attached
/// @param      times number of times
/// @param      ms cycle duration in ms
/// @param      level level for HIGH, default=true=positive logic, false=negative logic
///
void blink(uint8_t pin, uint8_t times, uint16_t ms, bool level = true);

Write Comments for Projects and Files

The templates come with comments, most of them populated. Here are the keywords I use the most.

For the main page with details about the author, copyright, licence, references and links.

Note the @mainpage keyword.

For a file with details about the author, copyright, licence, references and links.

By default, the projects and files templates include self-documenting headers.

  • For a function with details for parameters.



A result is documented with the keyword @return.

Use Snippets for Comments

The snippets for the documentation are under the User list.

The snippet for different details provides the keywords for note, warning, bug, to-do, test, ...

The snippet for code allows to include an example of code.

Doxygen includes many more options. Please refer to its documentation .