Can Doxygen easily be configured to recognise TODO and FIXME lines?

Iain Collins picture Iain Collins · Dec 16, 2011 · Viewed 16.8k times · Source

I've just installed and setup an instance of Doxygen, but out of the box it only finds TODO tags in code when marked in a block like:

/**
 * @todo Foo
 */

It doesn't seem to find:

// TODO Foo
// FIXME Bar
// @todo Baz

Most IDE's and bug trackers which handle parsing are fine with them, is there an easy way to configure Doxygen to find them and list them as ToDo items?

Answer

Chris picture Chris · Jan 4, 2012

There are a number of examples and methods we can use:

  • For a one line comment with valid doxygen commands (e.g. \todo) you would use

    /// \todo Some (optional) text
    

    Note the three forward slashes, not the usual two. See point three on the second list in the special documentation blocks section of the doxygen documentation. This can be used to add new todo items to your source code.

  • Generally one can define custom tags (like FIXME) by defining an alias in the Doxygen configuration file. For example

    ALIASES += FIXME="\todo"
    

    which will allow you to write \FIXME in your source code and the comments prefixed with \FIXME will be included in you todo list in the final documentation. The problem here is that you have to prefix your aliases with the \ (or @) symbol and begin the comment with three leading forward slashes which, if you want to leave the FIXMEs in your code as they are, is not an option.

  • Finally, an alternative method, and what I think you are looking for, would be to preprocess your source files using the INPUT_FILTER configuration file option. This option defines a command that is applied to each of your source files before doxygen builds the documentation, so we can define a command which replaces instances of TODO and FIXME with valid doxygen markup.

     INPUT_FILTER = "sed -e 's/\/\/.*FIXME/\/\/\/ \\todo/'"
    

    This filter replaces all instances of // FIXME (with any amount (or none) of whitespace between // and FIXME) with /// \todo. This substitution is made internally by doxygen only: your source files are not modified on disk.

Note: This last point was inspired by the accepted answer to the question Getting doxygen and MSVC TODO tags to work together. However, that answer used the FILE_VERSION_FILTER configuration option rather than INPUT_FILTER. I think that the latter (INPUT_FILTER) is actually more appropriate here. Also, the sed command used in that answer does not work for me.