Multi-bullet Doxygen @note?

Question

In non-Doxygen comments, I often have:

/* Lorem ipsum etc.
 *
 * Notes:
 * - A first note.
 * - Some other note note.
 */

But with Doxygen, I have @note (or \note), not @notes). So, should I use multiple @notes, or do I put all notes under the same @note?

Neill

Answer 1

The @note command results in a paragraph which format can be customized in the CSS file or in the style file when using Latex. So you can just use the markups like in a "normal" text:

/**
 * Bla bla...
 *
 * @note Even in a note you can use markups:
 *       - Your first note
 *       - Youre second note
 *
 * The note section ends with an empty line or the end of the comment.
 */

Sexism

Answer 2

You can do it either way; it's really a question of style/preference.

As you pointed out, Doxygen has the @note command, but not @notes. You can create your own command for @notes by editing the Doxyfile, and modifying the ALIASES = tag to read

ALIASES = "notes=@par Notes:\n"

With this, you can put the command @notes in the documentation, which will result in a user-defined paragraph with the heading

Notes:

As pointed out in the Doxygen documentation for the ALIAS tag, you can put \n's in the value part of an alias to insert newlines.

Uela

Ok, although the build people are going to complain that I'm wasting my time and their with minutiae rather than doing actual work... – Neill

I don't have an answer for that one. – Uela