Ticket #6180: proposed.rewords.patch

File proposed.rewords.patch, 3.0 KB (added by teratorn, 22 months 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>