Ticket #6180: proposed.rewords.patch

File proposed.rewords.patch, 3.0 KB (added by teratorn, 4 years ago)

proposed rewording of various paragraphs

  • defer-intro.xhtml

     
    1515  This document introduces <code base="twisted.internet.defer"
    1616  class="API">Deferred</code>s, Twisted's preferred mechanism for controlling
    1717  the flow of asynchronous code.  Don't worry if you don't know what that means
    18   yet, as the rest of this document sets out to explain exactly that.
     18  yet! That's why you are here!
    1919</p>
    2020
    2121<p>
     
    261261</p>
    262262
    263263<p>
    264   So, we've replaced the <q>order of lines is order of execution</q> with a
    265   deliberate, in-Python encoding of the order of execution,
    266   where <code class="python">d</code> represents the particular flow and
    267   <code class="python">d.addCallback</code> replaces <q>new line</q>.
     264  So, we've replaced the <q>order of lines is order of execution</q> model with a
     265  deliberate, in-Python encoding of the order of execution.
     266  The control-flow is represented by <code class="python">d</code>,
     267  and <code class="python">d.addCallback</code> declares your <q>next actions</q>.
    268268</p>
    269269
    270 <h2>A catalog of failures</h2>
    271 
    272270<p>
    273   Of course, programs generally consist of more than two lines, and exceptions
    274   add a delicate and pleasing spice to the whole experience.
     271  So far, so good.
    275272</p>
    276273
     274<h2>Getting it right: The failure cases</h2>
     275
    277276<p>
    278   In what follows, we are going to take each way of expressing order of
    279   operations in Python using sequences of lines
    280   and <code class="python">try</code>/<code class="python">except</code> and
    281   translate them into an equivalent built with <code class="API"
    282   base="twisted.internet.defer">Deferred</code>.
     277  In what follows, we are going to take each different way of expressing
     278  order of operations in normal Python (with code lines and
     279  <code class="python">try</code>/<code class="python">except</code>) and
     280  translate them into an equivalent code built with <code class="API"
     281  base="twisted.internet.defer">Deferred</code> objects.
    283282</p>
    284283
    285284<p>
    286   This is going to be a bit painstaking, but if you want to really understand
    287   how to use <code class="API" base="twisted.internet.defer">Deferred</code>s
    288   and how to understand and maintain code that uses <code class="API"
    289   base="twisted.internet.defer">Deferred</code>s, it is worth understanding
    290   each of these examples.
     285  This is going to be a bit painstaking, but if you really want to understand
     286  how to use <code class="API" base="twisted.internet.defer">Deferred</code>s,
     287  and maintain code that uses them, then it's worth understanding each example
     288  below.
    291289</p>
    292290
    293291<h3>One thing, then another, then another</h3>
     
    469467<p>
    470468  The order of <code class="python">addErrback</code>
    471469  and <code class="python">addCallback</code> matters.  In the next section, we
    472   can see what would happen when we them around.
     470  can see what will happen when we swap them around.
    473471</p>
    474472
    475473<h3>Handle an error for the entire operation</h3>