On Sun, 4 Jun 2006, Chapman Flack wrote:

> To address the "multiple places" issue and the fear of docs going stale,
> which is my fear too ... I think it would be swell to be able to make
> man pages straight from doxygenesque stuff in the source; a more practical
> step might be some kind of source comment that identifies a related
> man page, and a cvs script that puts the commit log and the manpage name
> on the queue of some daemon-with-eyeballs who can confirm that the
> docs aren't now lying.

I very much agree with this since it, if nothing else, makes it easy for 
developers to update the implementation (since it's all located in a 
single source file). It also makes it easier for people reading the source 
to understand what the interface guarantees and what the interface does 
not guarantee, and compare that with the actual implementation.