[capi-sig] Documenting a C/Py API

[Barry Warsaw]

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

On Jul 4, 2007, at 12:00 PM, Campbell Barton wrote:

> For people who dont mind docstrings + online docs, how big are your
> projects?

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.

> Barry:
> 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.
>
> 	{"orthographic",
> 	 (getter)Camera_getOrtho, (setter)Camera_setOrtho, "\
> @ivar orthographic: When true this camera will render with no
> perspective.\n\
> @type orthographic: bool",
> 	 NULL},
> 	{"ipo",
> 	 (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",
> 	 NULL},

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.

- -Barry



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

iQCVAwUBRozo0XEjvBPtnXfVAQKkewQAinerU5Jc+jyMWD/6Drkx/3p7t9Z+MfFh
0t3NJt5fbY0VXJRh2R4ghApJpWXXNp1BQ3qy6YnRTb5zNhT+dz6V5iipenLdWyYg
ShE5MoHdhEPrEZlQMxgDzJNHBiAYtDelGdyyJEwspgmE6expbt8z1s6QvML2dGgQ
u147d9X2geo=
=VYpg
-----END PGP SIGNATURE-----