Recently I have been working with a few C source trees utilizing a system called Doxygen to generate an HTML version of parts of the source code comments. The general idea seems to be to offer a way of describing the public interface of a system (of course nothing stops you from also describing the internals).
In order to achieve this, you have to use special formatting and markup in the source code comments. Unfortunately, this makes the comments much less readable as they are, in the actual code. You also need to use a special tool to extract and format the comments into HTML.
This is an example of a contraption supposed to help, in this case by providing good documentation, but instead resulting in increased complexity, first in the form of additional tools, and second by obfuscating the original documentation. The obvious solution is to read the comments in the header files, without need for additional tools (neither for generating the documentation, nor for reading it).
The type of comment markup and source code documentation systems similar to Doxygen should not be confused with the idea of literate programming as introduced by Donald Knuth. Literate programming is more like writing an essay describing your problem and its solution, interspersed with snippets of code, so that a compilable source code can be extracted from the text.