Enhancement to the \todo command with doxygen

I use doxygen for my code development, and use a lot the \todo command: it allows me to quickly mention things that need to be done when I don't have time to do it at the moment. This way things don't get buried into my memory.

The problem is that this produces a list that is not sorted in any way: you can't distinguish between things that are important and things that are just some ideas that need to be tried. Just see an example of what an unordered list looks like, in some random project I came across: www.portaudio.com/docs/v19-doxydocs/todo.html.

If your list has 10 or less items, that's not too bad. However, if you manage a large project, you can easily end up with a list with several dozens of items, and this list then becomes useless: the day you happen to have some spare time, you just can't spot what's really important to do... I thought that there was some kind of feature lacking in doxygen, in order to produce some hierarchical "todo" list using different \todo commands (say, \todo1 for top-priority things to do, \todo2 for less important things, and so on).

So I suggested this feature on the doxygen list, to see if other people find it useful, and if it could be added to the wish-list (again, another "todo" list!)

I discovered that this was already possible, by defining an alias in the doxyfile. Thanks to Clemens Feige, he explained to me how to define new commands that do the job, based on the \xrefitem command.

Using this command is not obvious, so I post here the way to do it.

Using a text editor, open your doxyfile and find the ALIAS line, and add the following lines:

ALIASES += "todo1=\xrefitem todo1 \"High Priority Todo\" \"Todo high priority list\""
ALIASES += "todo2=\xrefitem todo2 \"Medium Priority Todo\" \"Todo medium priority list\""
ALIASES += "todo3=\xrefitem todo3 \"Low Priority Todo\" \"Todo low priority list\""

In your code, you can now use either \todo, that will end up in the classical unsorted "todo" page, or \todo1, \todo2, or \todo3. Run your doxyfile, and that's it!

For more about code documentation, you can check the following pages:

• docs.google.com/View?id=dgjz7z25_129f4sqrrdx
• en.wikipedia.org/wiki/Software_documentation
• en.wikipedia.org/wiki/Comparison_of_documentation_generators