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.
|