[capi-sig] Documenting a C/Py API
barry at python.org
Thu Jul 5 14:49:21 CEST 2007
-----BEGIN PGP SIGNED MESSAGE-----
On Jul 4, 2007, at 12:00 PM, Campbell Barton wrote:
> For people who dont mind docstrings + online docs, how big are your
Our project was pretty big. I don't have exact numbers any more, but
I'd say on the order of maybe two dozen C implemented classes with
several hundred methods and properties in total.
> I just did a quick check on Blender/Python epydocs and there are 1297
> functions and 868 attributes and 73 classes == ~2238 doc strings.
I'm not counting stuff implemented in Python, which was probably 2-5
times the size of our C stuff. OTOH, our C classes were the core of
our model so we took great pains to document them accurately.
> Looks like this is a workable solution that Ill go ahead with.
> I was hoping there was some kind of triple quoting in C :/
> \n\ at the end of every line is a PITA, Though with search
> replace it
> can be added after writing..
> - Thanks for the hint regarding 1024 chars.
> EpyDocs as C strings aren't so bad, heres an example (for people other
> then Barry) of how it looks for getseters.
> (getter)Camera_getOrtho, (setter)Camera_setOrtho, "\
> @ivar orthographic: When true this camera will render with no
> @type orthographic: bool",
> (getter)Camera_getIpo, (setter)Camera_setIpo, "\
> @ivar ipo: The ipo linked to this camera data object.\n\
> Assign None to clear the ipo from this camera.\n\
> @type ipo: Blender Ipo",
Just to relate my own experiences here. I would typically include a
PyDoc_STRVAR() call right before the function's static definition,
instead of including the docstring in the structure definition. I
found that was cleaner and made it easier to update the docstring
when the function was updated. YMMV of course.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.7 (Darwin)
-----END PGP SIGNATURE-----
More information about the capi-sig