> If we're going to do something like this, then I suggest people take
> a look at doxygen (which can generate manual-type documentation from
> marked up comments in source files).

Well, my $0.02:

I don't know doxygen at all, but I've worked with various similar things
during my professional life. I have never seen this approach succeed.

I'm a big fan of

 - free form comment blocks preceding functions that need it
 - good (but mostly short) comments in header files
 - extensive use of asserts and similar run-time checks
 - extensive (internal) documentation similar to our section 9 man pages
 - special case docs in HTML format at some well known place (sometimes
   you just need graphics to explain something)

But that's just me, and what we ended up doing at my company (after trying yet
another tools when we started from scratch last year)

Martin