deferred.always: Added note for parameters changing order

Fixes gh-763
Closes gh-779

Author: AurelioDeRosa

entries/deferred.always.xml

@@ -17,6 +17,7 @@
   <desc> Add handlers to be called when the Deferred object is either resolved or rejected. </desc>
   <longdesc>
     <p>The argument can be either a single function or an array of functions. When the Deferred is resolved or rejected, the <code>alwaysCallbacks</code> are called. Since <code>deferred.always()</code> returns the Deferred object, other methods of the Deferred object can be chained to this one, including additional <code>.always()</code> methods. When the Deferred is resolved or rejected, callbacks are executed in the order they were added, using the arguments provided to the <a href="/deferred.resolve/"><code>resolve</code></a>, <a href="/deferred.reject/"><code>reject</code></a>, <a href="/deferred.resolveWith/"><code>resolveWith</code></a> or <a href="/deferred.rejectWith/"><code>rejectWith</code></a> method calls. For more information, see the documentation for <a href="/category/deferred-object/">Deferred object</a>.</p>
+    <p><strong>Note:</strong> The <code>deferred.always()</code> method receives the arguments that were used to <code>.resolve()</code> or <code>.reject()</code> the <code>Deferred</code> object, which are often very different. For this reason, it's best to use it only for actions that do not require inspecting the arguments. In all other cases, use explicit <a href="/deferred.done/"><code>.done()</code></a> or <a href="/deferred.fail/"><code>.fail()</code></a> handlers since the arguments will have well-known orders.</p>
   </longdesc>
   <example>
     <desc>Since the <a href="/jQuery.get/"><code>jQuery.get()</code></a> method returns a <code>jqXHR</code> object, which is derived from a Deferred object, we can attach a callback for both success and error using the <code>deferred.always()</code> method.</desc>