Jachym Holecek wrote:
> > The thing is that we already have documentation for frameworks,
> > functions and data structures in manual pages; duplicating it inside
> > source code is not a very good idea, as I see it.
> 
> True, plus doxygening the source makes it harder to read (too much
> comments when you want to see code, too much code when you're seeking
> for a comment.) At least that's my brief experience w/ Doxygen...

http://www.stack.nl/~dimitri/doxygen/docblocks.html

Scan for "Documentation at other places":

"Doxygen allows you to put your documentation blocks practically anywhere
(the exception is inside the body of a function or inside a normal C style
comment block)."  AIUI, that includes separate files.  

With a little cleverness, it may be possible to incorporate some or all of
the manual page in Doxyen's output.  That would allow the doxy output to
be a superset of what we already have, with advantages like call-tree
graphs.  

--jkl