[Twisted-Python] twisted.enterprise docs suck

[Andrew Bennetts]

Glyph wrote:
> >   * Am I demonstrating "best practice" use of twisted.enterprise, or should
> >     I be structuring my code differently?
> 
> There is one slight modification I'd make.  Typically, a method that
> calls runOperation will return its result, since presumably you are
> writing external code that uses the service and expects some way to hook
> into results being available :-).

Ok, so how about if I change the last example to:

    class AgeDatabase(adbapi.Augmentation):
        """A simple example that can retrieve an age from the database"""
        def getAge(self, name):
            # Define the query
            sql = """SELECT Age FROM People WHERE name = ?"""
            # Run the query, and set a callback to run when done
            return self.runOperation(sql, name)


    def gotAge(resultlist, name):
        """Callback for handling the result of the query"""
	age = resultlist[0][0]          # First field of first record
	print "%s is %d years old" % (name, age)

    db = MyDatabase(dbpool)

    # These will *not* block.  Hooray!
    db.getAge("Andrew").addCallbacks(gotAge, db.operationError, 
                                     callbackArgs=name).arm()
    db.getAge("Glyph").addCallbacks(gotAge, db.operationError,
                                    callbackArgs=name).arm()

If this looks sane to you, I'll update the example and the surrounding text at
poetry.puzzling.org/twisted_db.html.

> > If someone wants to place this (or an edited version of it) on
> > twistedmatrix.com, or distribute it with Twisted, or both, they are welcome.
> 
> Will do.  We've got lots of docs to write, and we'll integrate these as
> soon as I have some time.  Thanks for relieving a bit of that burden!

Actually, it was suggested to me that I should be more explicit with my
licencing of that document.  I haven't had time to probably examine
documentation licences, so I'll just state this instead: I donate the copyright
to that tutorial to the Twisted developers (i.e. Twisted Matrix Laboratories).
Basically, do what you like, I won't sue :)

-Andrew.