improve docs about a+ differences

archive/v0.1.3/change-log.html

@@ -60,6 +60,13 @@
 						</div>
 						<div class="col(9,9,12)">
 							<h2 id="change-log">Change Log</h2>
+<p><a href="/mithril/archive/v0.1.3">v0.1.3</a> - maintenance</p>
+<h3 id="bug-fixes-">Bug Fixes:</h3>
+<ul>
+<li>diff no longer touch the DOM when processing <code>style</code> attributes and event handlers</li>
+<li>returning a thennable to a resolution callback in <code>m.deferred().promise</code> now causes the promise to adopt its state </li>
+</ul>
+<hr>
 <p><a href="/mithril/archive/v0.1.2">v0.1.2</a> - maintenance</p>
 <h3 id="news-">News:</h3>
 <ul>

archive/v0.1.3/mithril.deferred.html

@@ -79,6 +79,32 @@ greetAsync()
     .then(function(value) {return value + " world"})
     .then(function(value) {console.log(value)}); //logs &quot;hello world&quot; after 1 second</code></pre>
 <hr>
+<h3 id="differences-from-promises-a-">Differences from Promises/A+</h3>
+<p>For the most part, Mithril promises behave as you&#39;d expect a <a href="http://promises-aplus.github.io/promises-spec/">Promise/A+</a> promise to behave, but with a few key differences:</p>
+<p>Mithril promises forward a value downstream if a resolution callback returns <code>undefined</code>. This allows simpler debugging of promise chains:</p>
+<pre><code class="lang-javascript">var data = m.request({method: &quot;GET&quot;, url: &quot;/data&quot;})
+    .then(console.log) //Mithril promises let us debug like this
+    .then(doStuff)
+
+var data = m.request({method: &quot;GET&quot;, url: &quot;/data&quot;})
+    .then(function(value) { // Promises/A+ would require us to declare an anonymous function
+        console.log(value) // here&#39;s the debugging snippet
+        return value // and we need to remember to return the value as well
+    })
+    .then(doStuff) // or else `doStuff` will break</code></pre>
+<p>Another subtle difference is that the Promises/A+ require a callback to run in a different execution context than its respective <code>then</code> method. This requirement exists to support an obscure edge cases and incurs <a href="http://thanpol.as/javascript/promises-a-performance-hits-you-should-be-aware-of/">a significant performance hit on each link of a promise chain</a>. To be more specific, the performance hit can come either in the form of a 4ms minimum delay (if the implementation uses <code>setTimeout</code>), or from having to load a <a href="https://raw.githubusercontent.com/NobleJS/setImmediate/master/setImmediate.js">bunch of hacky polyfill code</a> for a <a href="https://developer.mozilla.org/en-US/docs/Web/API/Window.setImmediate">feature that is not being considered for addition by some browser vendors</a>.</p>
+<p>To illustrate the difference between Mithril and A+ promises, consider the code below:</p>
+<pre><code class="lang-javascript">var deferred = m.deferred()
+
+deferred.promise.then(function() {
+    console.log(1)
+})
+
+deferred.resolve(&quot;value&quot;)
+
+console.log(2)</code></pre>
+<p>In the example above, A+ promises are required to log <code>2</code> before logging <code>1</code>, whereas Mithril logs <code>1</code> before <code>2</code>. Typically <code>resolve</code>/<code>reject</code> are called asynchronously after the <code>then</code> method is called, so normally this difference does not matter.</p>
+<hr>
 <h3 id="signature">Signature</h3>
 <p><a href="how-to-read-signatures.html">How to read signatures</a></p>
 <pre><code class="lang-clike">Deferred deferred()

docs/change-log.md

@@ -1,5 +1,14 @@
 ## Change Log
 
+[v0.1.3](/mithril/archive/v0.1.3) - maintenance
+
+### Bug Fixes:
+
+-	diff no longer touch the DOM when processing `style` attributes and event handlers
+-	returning a thennable to a resolution callback in `m.deferred().promise` now causes the promise to adopt its state 
+
+---
+
 [v0.1.2](/mithril/archive/v0.1.2) - maintenance
 
 ### News:

docs/mithril.deferred.md

@@ -29,6 +29,46 @@ greetAsync()
 
 ---
 
+### Differences from Promises/A+
+
+For the most part, Mithril promises behave as you'd expect a [Promise/A+](http://promises-aplus.github.io/promises-spec/) promise to behave, but with a few key differences:
+
+Mithril promises forward a value downstream if a resolution callback returns `undefined`. This allows simpler debugging of promise chains:
+
+```javascript
+var data = m.request({method: "GET", url: "/data"})
+	.then(console.log) //Mithril promises let us debug like this
+	.then(doStuff)
+	
+var data = m.request({method: "GET", url: "/data"})
+	.then(function(value) { // Promises/A+ would require us to declare an anonymous function
+		console.log(value) // here's the debugging snippet
+		return value // and we need to remember to return the value as well
+	})
+	.then(doStuff) // or else `doStuff` will break
+
+```
+
+Another subtle difference is that the Promises/A+ require a callback to run in a different execution context than its respective `then` method. This requirement exists to support an obscure edge cases and incurs [a significant performance hit on each link of a promise chain](http://thanpol.as/javascript/promises-a-performance-hits-you-should-be-aware-of/). To be more specific, the performance hit can come either in the form of a 4ms minimum delay (if the implementation uses `setTimeout`), or from having to load a [bunch of hacky polyfill code](https://raw.githubusercontent.com/NobleJS/setImmediate/master/setImmediate.js) for a [feature that is not being considered for addition by some browser vendors](https://developer.mozilla.org/en-US/docs/Web/API/Window.setImmediate).
+
+To illustrate the difference between Mithril and A+ promises, consider the code below:
+
+```javascript
+var deferred = m.deferred()
+
+deferred.promise.then(function() {
+	console.log(1)
+})
+
+deferred.resolve("value")
+
+console.log(2)
+```
+
+In the example above, A+ promises are required to log `2` before logging `1`, whereas Mithril logs `1` before `2`. Typically `resolve`/`reject` are called asynchronously after the `then` method is called, so normally this difference does not matter.
+
+---
+
 ### Signature
 
 [How to read signatures](how-to-read-signatures.md)