Choosing between attention, note, remark, todo and warning in Doxygen

Question

The documentation generator Doxygen allows to mark a piece of comment as attention, note, remark, todo or warning.

What guidelines should I follow to properly classify a comment as one of them?

Answer 1

All of these tags are used for the purpose of highlighting a section of the documentation as being particularly notable, in comparison to other sections that are not so tagged. They are all used to draw the reader's attention to the tagged paragraph.

The Note is the most generic tag, and is the one to use in most cases where you want the reader to "take notice" of the matter described in the section.

The Attention tag can be used to highlight a particularly important note, one that you don't want the reader to overlook.

The Warning tag should be used instead of Attention when there may be negative consequences to consider if the reader isn't careful in how he uses the item being documented.

The Remark and Remarks tags can be used for notes that have lesser importance. If you want to describe something in an "oh, by the way" sense, the Remark tag is useful for that.

The Todo tag is used differently than the others you listed. It is usually used to indicate that the code being described in the comment has one or more unfinished aspects. This alerts both code users and code writers that a feature or bug needs to be addressed in a later revision of the pertinent section of code. Doxygen has a cool feature where it will list all Todos together in their own section in the generated output. This can be turned off by editing the Doxyfile and changing the line GENERATE_TODOLIST = YES to GENERATE_TODOLIST = NO.

Related to the Todo tag is the Bug tag, which can be used specifically to tag documentation describing a software bug. Likewise, the Doxyfile has a GENERATE_BUGLIST = YES line that causes all Bugs to be listed in their own section; this can be turned off with GENERATE_BUGLIST = NO.