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