Docs for for…from (#4368)

* Documentation of `for...from` for iterating over generator functions

* Add note that the CoffeeScript compiler does not, in fact, generate JavaScript that runs in every JavaScript runtime 😢

Cakefile

@@ -59,7 +59,7 @@ codeFor = ->
     cshtml = "<pre><code>#{hljs.highlight('coffeescript', cs).value}</code></pre>"
     # Temporary fix until highlight.js adds support for newer CoffeeScript keywords
     # Added in https://github.com/isagalaev/highlight.js/pull/1357, awaiting release
-    if file in ['generators', 'modules']
+    if file in ['generator_iteration', 'generators', 'modules']
       cshtml = cshtml.replace /(yield|import|export|from|as|default) /g, '<span class="keyword">$1</span> '
     jshtml = "<pre><code>#{hljs.highlight('javascript', js).value}</code></pre>"
     append = if executable is yes then '' else "alert(#{executable});"

documentation/examples/generator_iteration.coffee

@@ -0,0 +1,13 @@
+fibonacci = ->
+  [previous, current] = [1, 1]
+  loop
+    [previous, current] = [current, previous + current]
+    yield current
+  return
+
+getFibonacciNumbers = (length) ->
+  results = [1]
+  for n from fibonacci()
+    results.push n
+    break if results.length is length
+  results

documentation/index.html.js

@@ -107,8 +107,17 @@
       compiles one-to-one into the equivalent JS, and there is
       no interpretation at runtime. You can use any existing JavaScript library
       seamlessly from CoffeeScript (and vice-versa). The compiled output is
-      readable and pretty-printed, will work in every JavaScript runtime, and tends
-      to run as fast or faster than the equivalent handwritten JavaScript.
+      readable, pretty-printed, and tends to run as fast or faster than the
+      equivalent handwritten JavaScript.
+    </p>
+
+    <p>
+      The CoffeeScript compiler goes to great lengths to generate output JavaScript
+      that runs in every JavaScript runtime, but there are exceptions. Use
+      <a href="#generator-functions">generator functions</a> only if you know that your
+      <a href="http://kangax.github.io/compat-table/es6/#test-generators">target
+      runtimes can support them</a>. If you use <a href="#modules">modules</a>, you
+      will need to <a href="#modules-note">use an additional tool to resolve them</a>.
     </p>
 
     <p>
@@ -577,6 +586,9 @@ Block
       check to avoid properties that may be inherited from the prototype, use<br />
       <code>for own key, value of object</code>
     </p>
+    <p>
+      To iterate a generator function, use <code>from</code>.
+      See <a href="#generator-iteration">Generator Functions</a>.
     <p>
       The only low-level loop that CoffeeScript provides is the <b>while</b> loop. The
       main difference from JavaScript is that the <b>while</b> loop can be used
@@ -864,8 +876,9 @@ Block
       constructed.
     </p>
     <p>
+      <span id="generator-functions" class="bookmark"></span>
       CoffeeScript functions also support
-      <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*">ES6 generator functions</a>
+      <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*">ES2015 generator functions</a>
       through the <code>yield</code> keyword. There's no <code>function*(){}</code>
       nonsense &mdash; a generator in CoffeeScript is simply a function that yields.
     </p>
@@ -874,6 +887,11 @@ Block
       <code>yield*</code> is called <code>yield from</code>, and <code>yield return</code>
       may be used if you need to force a generator that doesn't yield.
     </p>
+    <p>
+      <span id="generator-iteration" class="bookmark"></span>
+      You can iterate over a generator function using <code>for&hellip;from</code>.
+    </p>
+    <%= codeFor('generator_iteration', 'getFibonacciNumbers(10)') %>
 
     <p>
       <span id="embedded" class="bookmark"></span>
@@ -975,6 +993,7 @@ Block
     </p>
     <%= codeFor('modules') %>
     <p>
+      <span id="modules-note" class="bookmark"></span>
       Note that the CoffeeScript compiler <strong>does not resolve modules</strong>; writing an
       <code>import</code> or <code>export</code> statement in CoffeeScript will produce an
       <code>import</code> or <code>export</code> statement in the resulting output.
@@ -1393,7 +1412,7 @@ six = -&gt;
       <%= releaseHeader('2015-09-03', '1.10.0', '1.9.3') %>
       <ul>
         <li>
-          CoffeeScript now supports ES6-style destructuring defaults.
+          CoffeeScript now supports ES2015-style destructuring defaults.
         </li>
         <li>
           <code>(offsetHeight: height) -&gt;</code> no longer compiles. That
@@ -1502,7 +1521,7 @@ six = -&gt;
       <%= releaseHeader('2015-01-29', '1.9.0', '1.8.0') %>
       <ul>
         <li>
-          CoffeeScript now supports ES6 generators. A generator is simply a function
+          CoffeeScript now supports ES2015 generators. A generator is simply a function
           that <code>yield</code>s.
         </li>
         <li>