[Twisted-Python] API docs

[Christopher Armstrong]

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/