[capi-sig] Documenting a C/Py API

[Barry Warsaw]

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

On Jul 2, 2007, at 10:14 PM, Campbell Barton wrote:

> Barry pointed out that docs could be generated with epydoc inspecting
> the C api directly,
> Id be interested to know if you had much epydoc spesific stuff in  
> these
> docstrings, though i was aware this was possible in some cases, you  
> end
> up with nicer docs if they include formatting tags.

I'm not sure if you were asking me this question, but I'll answer  
anyway :).  Yes!  We put epydoc markup in our C API docstrings and  
epydoc almost all the right things.  As I mentioned there were a  
couple of quirks due to import weirdness or inheritance but 98% of  
the docstrings worked great.

I should note one other bit of funny business,  Writing multiline  
docstrings in C is a royal PITA of course, especially if you ever  
have to re-fill a paragraph.  Ain't no TQS's there!  The one thing  
that bit us fairly often was a limit on the number of characters  
inside a string literal that Microsoft's compiler imposed on us.  Our  
code was portable between gcc and MSVC (Studio Enterprise .NET  
Ultramarine Whizzy XP Light and Happiness Edition 2003 (tm)(r)(c) 
(blah)). gcc never had a problem but with MSVC we couldn't use the \n 
\ trick after 1024 characters.  We'd have to close the literal and  
start again.  There was probably some magic config buried under  
30,000 menu options, but we never found it.

- -Barry


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

iQCVAwUBRorgpHEjvBPtnXfVAQLWnQQAhU+JslzLZYLeXEMl5/cSjugAgU1YJNdx
2xzp4qK1Oi/RYgRReoCBEvbNA/9+h3OARda+Uj9GiBhTEZziC+M3uqTqEFltFIt2
zVXKF9iHB4jNwiuu0L5e/hA3CxkFOKFCypt8JLzi9nJzOy3iTQv+KYqFfM8lMZvu
hzheqIubQ6I=
=WayZ
-----END PGP SIGNATURE-----