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
/// /// @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.
- Please refer to its documentation .
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 @
/// /// @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.
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 .