[Doxygen-develop] Simple @todo improvements?

[Luna K. <lis...@ne...>]

Hi,

(I'm new to Doxygen, so I apologize if the things below are 
a matter of config settings. At the moment it seems they aren't.)

------------

@todo items appear not to be collected globally (or on a
file level), irrespective of being in a special comment or 
not. Only those get listed that are in comments related
to classes, methods etc.

Is this true, or am I just missing something?

If so, this would be nice to amend, as many todo items are 
pretty generic things, very frequently not associated with 
any already existing language constructs, but are feature/
improvement/correction suggestions and ideas etc. on a 
project-global or a module/file level.

In my practice, the "global" todo stuff is actually far 
more important than the "fixme"-like comments relevant to 
certain code constructs (classes etc.). So, given that 
Doxygen already supports the latter very nicely, it would 
be quite natural to do same for the global ones, too.

(The Related Pages --> Todo List is already straightforward 
place for listing the project-global @todo items, as is the 
File List for the file-global todo item collections.)

------------

Another thing: developers tend to have their own todo listings
already, somewhere at the beginning or end of a file, usually 
formatted simply like e.g.:

/* TODO:

    - This is something to do.

    - And this one is a very common multi-line
      todo item.

    - And here comes a third one, which is not only
      multi-line, but is a multi-paragraph one.

      (Can also possibly contain URLs, code fragments, 
      but all properly indented.)
         
*/

It would be extremely helpful if Doxygen could take care 
of these and could include these existing lists without 
forcing the programmer

    - to unnaturally attach the comment block to some 
      language construct [again, this may not be true, 
      I'm a Doxygen newbie, and I might have just missed 
      something in the docs.]

    - placing a "@todo" before each and every item on
      the list, likely breaking his formatting style and 
      possibly also the compatibiliy with his already 
      existing todo-management stuff.

Ideally, a simple code change like this should be enough:

/** @todo:

    - This is something to do.

    - And this one is a multi-line
      todo item.

    - And here come a third one, which is not only
      a multi-line one, but even a multi-paragraph one.

      (Can also possibly contain URLs, code fragments, 
      but all properly indented.)
*/

(I'd say an upper-case @TODO should also be accepted, but
that's just a personal itch.)

------------

BTW, if the user happens to already have some TODO management
logic in place already, where he also handles component-level 
TODO items (the subset Doxygen appears to support), he probably 
also uses some markup, similar to Doxygen's, but most likely 
not the same, like: !!TODO or [TODO:] or whatever.

It would be incredibly helpful if Doxygen would allow changing
the pattern by which it can find a todo/bug/... item!

(Of course this flexibility would be very handy for most of 
the other pattern constructs, too, but I digress...)

------------

OK, thanks for your patience!

Cheers,
Sz.