[Twisted-Python] Deferred documentation.

[Jasper St. Pierre]

(I screwed up my mailman preferences accidentally, so this is
formatted a bit haphazard from copy/paste)

> Thank you for tackling the impossible.

Thank you for the encouragement. I'm curious if you read both
documents, and if you had a preference toward one or the other. I
hopefully only want to have one "definitive deferred brief" in the
end, so a consensus on which road I should take would be would be
helpful:

* -Rewrite has a personal style: first-person perspective, relaxed
language, to-the-point-but-silly examples.

* -Fixup is a sort of gentler working of the current deferred doc that
tries to be a bit more gentle about what the user knows: I don't shove
the user full of an example involving some intricate intertwining of
Deferred.callback and reactor.callLater to introduce them to
callbacks, I instead opt to showcase the built-in HTTP client.

> I remember when reading the old docs the first time that one thing
> bothered me most and this was 'if I get a deferred back, then I'm kind
> of responsible for that beast' so what do I do with it besides adding
> call/errbacks'? I had a hard time and quite a few hours with the
> debugger to figure out the life cycle of a deferred. I also read
> gendefer.html over and over again while trying to figure out the
> relation of a deferred to the reactor, because somehow it must be that
> reactor.run() loop which in the end triggers either call- or errbacks.
>
> This might be typical questions from someone who grew up without garbage
> collection. My problem is, that for coding in a confident way I have to
> have a grasp of the innards of the system.
>
> Summed up
> - How does the life cycle of a deferred look like?
> - Who is responsible for a deferred?
> - If deferreds are related to the reactor, then how are they related?

An alternate goal of my efforts is to have a "rule list". Important
things about the guarantees Deferreds should be documented:

*If* you add more than one callback, *then* the return value of the
last callback will be used as the result for the next callback.
*If* you return a Deferred from a callback, *then* the callback chain
waits until the second Deferred is complete.

> Reading your two docs answers those questions I had back then,
> definitely an improvement.
>
> Minor glitches:
>
> link to node.js is >> http://nodejs.org/

I'm going to have to find new libraries anyway: gevent takes an
eventum-style approach that uses monkey-patches on urllib. I've seen
the callback approach before in a lot of other, different JavaScript
libs, hell, even the DOM-based addEventListener uses this a lot. I
just need to find a Python-based strawman to knock down.

> Thanks again, Werner

Thank you so much for the encouragement.