29

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?

Iain Collins
  • 6,774
  • 3
  • 43
  • 43
  • 3
    Doxygen comments tend to be within special comment blocks don't they? I think for a one line comment you would use `/// @todo Some text` (note the three forward slashes, not the usual two). See point three on the second list on [this](http://www.stack.nl/~dimitri/doxygen/docblocks.html) page. – Chris Dec 16 '11 at 14:42
  • Thanks, I'd totally missed that page, will check it out. [I'm not usually this lazy, I'm just pressed for time but trying to do this on the side so at least we have /something/ :)] – Iain Collins Dec 19 '11 at 12:18
  • @Chris, You should enter that as an answer, and Iain, you should accept it if it solved your problem. – tomlogic Jan 04 '12 at 01:59
  • @tomlogic Thanks for the advice - I've done this now. – Chris Jan 04 '12 at 11:45

1 Answers1

47

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.

Chris
  • 44,602
  • 16
  • 137
  • 156
  • This was all I could find too, ho-hum :( Have not had time to look at the configuration or the source to Doxygen to see how it works, accepting the answer as "No, it only finds TODO and FIXME statements marked up strictly as per the documentation" in lieu of other answers for now (but am not sure that's entirely correct). Thanks for the answer. – Iain Collins Jan 04 '12 at 18:01
  • Do you have `GENERATE_TODOLIST` set to `YES` in your configuration file? Also, is your `todo` in lowercase, and have you tried `\todo` instead of `@todo`? Finally, try using `//! \todo {optional text}` rather than `/// \todo {optional text}` – Chris Jan 04 '12 at 20:01
  • Yeah I do, the problem I have isn't getting it to show up TODO and FIXME style notes in the supported documented format (that works fine, as I've said in my question) but exactly as they are (i.e. with existing codebases, not written with Doxygen in mind). – Iain Collins Jan 05 '12 at 15:34
  • 1
    @IainCollins Sorry - I completely misunderstood the question. If I understand correctly now, you want doxygen to pick up the `TODO` and `FIXME` lines in your source without replacing them with the Doxygen commands. If this is the case, I have attempted to answer this in my edit above. – Chris Jan 05 '12 at 15:54
  • Thanks so much Chris! We really need something like this for the team but my hands have been full with no time to RTFM. This helps enormously. – Iain Collins Jan 06 '12 at 16:25
  • 1
    A little more advanced filter can catch different styles of comments: This filter works with C style comment (/* ... */) and 'TODO' comments too: `INPUT_FILTER = "sed -Ee 's,(//|/\*).*(TODO|FIXME),\1! \\todo ,'"` Replaces any *special comment* with `//! \todo` or `/*! \todo`, respective to the used commend style in the sources. – Florian Apr 21 '19 at 13:43