title: pipe() and then() documentation vs reality in jQuery 1.8
body: <h2>Update: This question is now out of date as the documentation is accurate and up to date.</h2>
  
  <p>I've been exploring the jQuery Deferred/Promise API for a bit and I'm very confused about the differences between <code>pipe()</code> and <code>then()</code> philosophically and in the jQuery documentation.  I've found that pipe() is just an alias for then() as of jQuery 1.8.</p>
  
  <p>From jQuery source:</p>
  
  <pre><code>// Keep pipe for back-compat
  promise.pipe = promise.then;
  </code></pre>
  
  <p>Yet the documentation is completely different for <code>pipe()</code> and <code>then()</code> as they supposedly have entirely different uses.</p>
  
  <p>Description for <code>then()</code>:</p>
  
  <blockquote>
    <p>Description: Add handlers to be called when the Deferred object is resolved or rejected.</p>
  </blockquote>
  
  <p>Description for <code>pipe()</code>:</p>
  
  <blockquote>
    <p>Description: Utility method to filter and/or chain Deferreds.</p>
  </blockquote>
  
  <p>I understand that historically they had slightly different behavior, but in the entirety of the <a href="http://api.jquery.com/deferred.pipe/" rel="noreferrer">documentation for pipe</a> or the <a href="http://api.jquery.com/deferred.then/" rel="noreferrer">documentation for then</a>, it doesn't even say that these two functions do the exact same thing now.</p>
  
  <p>So, here's my two part question:</p>
  
  <ol>
  <li>Why does the documentation between <code>pipe()</code> and <code>then()</code> differ as of jQuery 1.8?</li>
  <li>Why does <code>then()</code> return a <strong>new</strong> deferred object?  This behavior is completely undocumented (the <a href="http://api.jquery.com/deferred.then/" rel="noreferrer">docs just say it returns a Deferred, not that it's a new one</a>).  I understand that it has utility in doing so (namely to implement all of <code>pipe()</code>'s features), but philosophically why is it the case?  It's unnecessary given the description of <code>then()</code> (to attach handlers).</li>
  </ol>
  
  <p><strong>Update</strong></p>
  
  <p>I'll even go so far as to say the <code>then()</code> docs are misleading and inaccurate:</p>
  
  <blockquote>
    <p>Since deferred.then <strong>returns the deferred object</strong>, other methods of the deferred object can be chained to this one, including additional .then() methods.</p>
  </blockquote>
  
  <p>Maybe it's just vague, but it implies it returns the deferred object you called <code>then()</code> on for chaining, when in reality it returns an entirely new object....</p>
  
  <p><strong>Update Again</strong></p>
  
  <p>Seems the documentation is simply wrong/out of date!  So that answers why the documentation makes no mention of them being the same thing.  However, my second question still stands.  Is the reason <code>then()</code> returns a <strong>new</strong> deferred simply so that it and <code>pipe()</code> can be made equivalent?</p>