[Twisted-Python] Deferred documentation rewrite

[Itamar Shtull-Trauring]

On Fri, 2009-07-31 at 18:40 -0400, Edward Z. Yang wrote:
> You can view an initial draft of the rewrite here:
> 
> http://ezyang.com/twisted/defer2.html
> 
> For reference, this is the planned outline (X means done, ? means
> almost done):
> 
> X Synchronous to Asynchronous: The Method to the Madness
>     X Convert synchronous code to asynchronous code
>     X Why asynchronous?

It's great you're working on this! The docs on deferreds certainly need
help.

The problem with this is that it perpetuates the misunderstanding the
Deferreds *make* things asynchronous, even with the intro that says
otherwise. I think it's better to assume already asynchronous code,
handling the transition from synchronous to async in an intro event loop
howto. 

A better comparative exposition might be with normal callbacks, e.g.:

"def foo(x, gotResultCallback): pass" vs. "def foo(x): # return
Deferred".

At the very least having that async but callbacky version in the middle
helps understanding.

It also omits half the story: how you *create* Deferreds. There should
be a section on that as well.

An example involving a parser, where you just wave your hands about who
pushes data in to the parser exactly (so no need to go into event loop
details), may work well. In particular, the object that wants the result
of the parsing wants to get parse errors, *not* whoever pushes data in.
Often it's same object, but not always. Deferreds help with that.