documenting code

[Jeremy C. Reed]

What do you use (tools or techniques) for documenting code for design 
decisions, code examples, history of API/ABI changes, graphical 
supplements (like design diagrams), etc?

I'd like to generate both webpages that have full details plus manpages 
that have the synopsis, descriptions, return values, etc, but not all 
the design decisions nor images (of course) nor code examples which may 
be too long for a succinct manual page.

I don't want to document in multiple places -- don't want to be 
redundant. I'd like to keep this documentation very near the code (even 
embedded) so when code is updated, it is easy to remember or do the 
documentation also.

The code is mostly a mix of Python and C++.

Do you use pydoc and/or doxygen?

I see doxygen can insert images into the documentation, so could be used 
to insert design diagrams.

And doxygen has conditional \if and \ifnot for conditionally showing or 
not showing documentation (which could be used for manpages versus 
complete HTML).

I don't see image or manual page support for pydoc.

If you have any examples (original documentation and rendered results in 
HTML and man), please let me know.

Also if you have any developer guidelines that include documentation 
guidelines, please let me know.