[capi-sig] Documenting a C/Py API
cbarton at metavr.com
Wed Jul 4 18:00:43 CEST 2007
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
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
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",
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.
More information about the capi-sig