[capi-sig] Documenting a C/Py API

[Eric Huss]

> 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-A583-FBF3D93C59FB%40gradient.cis.upenn.edu

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:

http://ehuss.org/mysql/api/

-Eric