Doxygen supports only one detailed comment per object (function, struct, etc). This causes some 
serious usability issues.

For instance, we (my workplace) use a detailed comment describing all functions in each of our header 
files. But we would also like to be able to sprinkle \todo commands within the source, near the line(s) 
that needs work. But this causes Doxygen to drop the entire previous detailed comment. Of course, we 
can work around this by always putting the \todo commands in the header file. But that is clearly not 
how that command is intended to work.

As another example, we would like to break function documentation into two pieces. First, public 
documentation for external consumption by customers (in the header files). And second, internal 
documentation for ourselves, in the source files, controlled by \if-\endif commands. 
But this cannot be done because of this restriction. There are other special commands that also make 
sense to separate from the main detailed comment, such as \note.

Although it may make perfect logical sense to require a single detailed comment, in practice it is a 
rather user-hostile requirement. Coming from the point of view of a user rather than the author of 
Doxygen, this restriction simply doesn't make sense. We view it as the single real issue with Doxygen. 
Fixing this would greatly improve the flexibility of Doxygen, in ways that  would be hard to compare 
with other new features.

The attached example files demonstrate how we would expect Doxygen to work. The .h file contains a 
function that has a \brief command and some public information about the function. The .c file 
contains more internal-type documentation of the function. Of course, when you generate the 
documentation, only the comments in the source file are applied. We would expect everything in the 
source file to be appended after that in the header files.

Thanks.