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@twistedmatrix.com >> http://twistedmatrix.com/users/carmstro.twistd/