[Twisted-Python] API docs
Christopher Armstrong
carmstro at twistedmatrix.com
Fri Jul 19 01:17:31 EDT 2002
I was talking to MetaCosm, and he said the template for API docs he uses
in his professional projects is like so:
"""
Usage:
foo() -> baz
Examples:
if blah(): foo()
Big Picture: (!!)
This class is meant to be used in a Quuxer, and you should usually
override the getBaz method to return a Spam instance, although it's not
required.
NOTES:
This class is currently in a state of flux; it will soon be
refactored, so watch out for API changes
"""
etc.
The main thing here is "Big Picture", which should give the method/class
some context. NOTES is mainly for temporary stuff; It's probably not
crucial to be in the docstrings (probably it should just be in near-by
#XXX comments). So yeah, I urge people who are writing docstrings to put
stuff into context; I'll try to do the same thing. Whether or not you
use a similar format isn't really important, but it seems sane enough to
me. We'll probably be doing a lot of this during the 0.99.0 cycle, but
it's never too early to start improving documentation :)
Anyway, enough rambling: off to bed with me.
--
Chris Armstrong
<< radix at twistedmatrix.com >>
http://twistedmatrix.com/users/carmstro.twistd/
More information about the Twisted-Python
mailing list