[capi-sig] Documenting a C/Py API

[Barry Warsaw]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Jul 2, 2007, at 9:30 AM, Campbell Barton wrote:

> 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.

This isn't necessarily true.  In a previous life, I was doing tons of  
C API stuff, essentially building and maintaining a big embedded/ 
extended Python application.  We docstring'd all of our C API and  
used epydoc to generate our API documentation.  It worked very well,  
with a few caveats.

First, epydoc had some problems in earlier versions, for example, the  
fact that a class's docstring and its constructor's docstring both  
live in the same slot in C.  IIRC, epydoc also had some problems with  
certain C inheritance style we were using, and a bunch of other minor  
problems.  AFAIK, these have mostly been addressed with newer epydoc  
versions, though I honestly haven't looked at it for 6+ months.

Second, and more importantly, because of the nature of our app, we  
had to run epydoc programmatically, inside the application's shell.   
I think you're forced to use epydoc's import-based discovery  
mechanisms when docstring'ing C code, so your modules have to be  
importable.  Because we were an embedded application, the package  
namespace for our C code wasn't available except when the application  
shell was run.  Therefore we added a command line option that would  
run the epydoc stuff, once Python was initialized and the extension  
modules were available.

Other than that, we really didn't have to do much special to  
docstring our C functions, provide them in normal Python interactive  
interpreter help, and have nicely generated epydoc documentation.   
All of our docstrings lived right in C and were attached to the C  
functions using the normal Python C API structures.

I wish I could post some examples, but the code was closed-source and  
the company no longer exists. ;)

- -Barry


-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.7 (Darwin)

iQCVAwUBRokyCXEjvBPtnXfVAQIYhwP/R/y9Jq18PaQzOkhDBdjHKsxo0bOx3FUN
OFTYsDarPHpuxUVSRTqswjhi1Q/izP+NKcKeRRNA2KLqyrsMcVi0iWcMiqqZmosB
ZZqSTmTgCXRqjoEZuCBHOb94YCYyn8J93ein95W0E2enUNVmYfNoL67/uqSVlUm1
wHS37QyBowQ=
=UrSn
-----END PGP SIGNATURE-----