[capi-sig] Documenting a C/Py API

[Campbell Barton]

Barry Warsaw wrote:
> -----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


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

I just did a quick check on Blender/Python epydocs and there are 1297 
functions and 868 attributes and 73 classes == ~2238 doc strings.

(got my numbers from running this in the epydoc dir)
  cat *.py | grep "def " | grep ":" | wc -l
  cat *.py | grep "class " | grep ":" | wc -l
  cat *.py | grep "@ivar" | wc -l


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},


adding some special tag like ((reference some_example.py)) that can be 
inserted when generating the Py files is no big deal and would read well 
in the docstrings too.

Thanks again.
- Cam