In Blender3D were doing an API refactor and Im looking at better ways to write the Python C/API documentation.
At the moment we use epydoc, Its all Iv used so I don't have much to compare it to.
If you havnt used it, its basically a way to add formatting to your normal .py docstrings so they can be converted into HTML or PDF.
This works well with python only projects but is not somthing you can do in C without some manual docstring extraction from the C/API.
I use epydoc extensively, with a lot of C code. Actually, a lot of it is Pyrex, so it's much easier to write and is more natural, but the basics should be the same.
The latest versions of epydoc are much better. I would suggest getting the latest straight from subversion, it is pretty stable.
I think Barry may have mentioned this, but you can put __init__ signatures in the type docstring. I haven't experimented with this, much. This isn't completely documented, you can look in epydoc/docstringparser.py and look for SIGNATURE_RE. See this message from some detail:
http://sourceforge.net/mailarchive/message.php?msg_name=8D22D41A-730E-42B4-A...
I have one of my projects up where you can look at the docs generated by epydoc. The majority of this code is in Pyrex:
-Eric