docs: fixes and updates (#130)

* Many typo/grammar fixes and clarification improvements
* Replaced the old pre-Julia-1.0 style iterator interface shown in the
  "internals" page with the correct `iterate` interface that's actually
  used by the package
* Fix install instructions to import `Pkg` first, and sync the authors
  list with what's in the README

Author: digital-carver

README.md

@@ -59,8 +59,10 @@ end
 for fib in fibonacci(10)
   println(fib)
 end
+```
 
-# Example with specifies the length
+```julia
+# Example which specifies the length
 using ResumableFunctions
 
 @resumable length=n^2 function fibonacci(n::Int) :: Int

docs/src/index.md

@@ -1,6 +1,6 @@
 # ResumableFunctions
 
-C# style generators a.k.a. semi-coroutines for Julia.
+*C# style generators a.k.a. semi-coroutines for Julia.*
 
 C# has a convenient way to create iterators using the `yield return` statement. The package `ResumableFunctions` provides the same functionality for the Julia language by introducing the `@resumable` and the `@yield` macros. These macros can be used to replace the `Task` switching functions `produce` and `consume` which were deprecated in Julia v0.6. `Channels` are the preferred way for inter-task communication in julia v0.6+, but their performance is subpar for iterator applications.
 
@@ -40,12 +40,14 @@ end
 
 `ResumableFunctions` is a registered package and can be installed by running:
 ```julia
+using Pkg
 Pkg.add("ResumableFunctions")
 ```
 
 ## Authors
 
 * Ben Lauwens, Royal Military Academy, Brussels, Belgium.
+* JuliaDynamics and QuantumSavory volunteers.
 
 ## License
 

docs/src/internals.md

@@ -1,11 +1,16 @@
 # Internals
 
-The macro `@resumable` transform a function definition into a finite state-machine, i.e. a callable type holding the state and references to the internal variables of the function and a constructor for this new type respecting the method signature of the original function definition. When calling the new type a modified version of the body of the original function definition is executed:
-  - a dispatch mechanism is inserted at the start to allow a non local jump to a label inside the body;
-  - the `@yield` statement is replaced by a `return` statement and a label placeholder as endpoint of a non local jump;
-  - `for` loops are transformed in `while` loops and
-  - `try`-`catch`-`finally`-`end` expressions are converted in a sequence of `try`-`catch`-`end` expressions with at the end of the `catch` part a non local jump to a label that marks the beginning of the expressions in the `finally` part.
-The two last transformations are needed to overcome the limitations of the non local jump macros `@goto` and `@label`.
+The macro `@resumable` transforms a function definition into a finite state-machine, i.e.
+  * a callable type holding the state and references to the internal variables of the function,  and
+  * a constructor for this new type respecting the method signature of the original function definition. 
+
+When calling an instance of this new type, a modified version of the body of the original function definition is executed:
+  - a dispatch mechanism is inserted at the start to allow a non-local jump to a label inside the body;
+  - the `@yield` statement is replaced by a `return` statement and a label placeholder as endpoint of a non-local jump;
+  - `for` loops are transformed into `while` loops; and
+  - `try`-`catch`-`finally`-`end` expressions are converted into a sequence of `try`-`catch`-`end` expressions; at the end of the `catch` part, a non-local jump is inserted to a label that marks the beginning of the expressions in the `finally` part.
+
+The last two transformations are needed to overcome the limitations of the non-local jump macros `@goto` and `@label`.
 
 The complete procedure is explained using the following example:
 
@@ -27,18 +32,19 @@ The function definition is split by `MacroTools.splitdef` in different parts, eg
 
 ## For loops
 
-`for` loops in the body of the function definition are transformed in equivalent while loops:
+`for` loops in the body of the function definition are transformed into equivalent `while` loops:
 
 ```julia
 begin
   a = 0
   b = 1
   _iter = 1:n-1
-  _iterstate = start(_iter)
-  while !done(_iter, _iterstate)
-    i, _iterstate = next(_iter, _iterstate)
+  state = iterate(_iter)
+  while state !== nothing
+    i, _iterstate = state
     @yield a
     a, b = b, a + b
+    state = iterate(_iter, _iterstate)
   end
   a
 end
@@ -79,9 +85,9 @@ mutable struct ##123 <: ResumableFunctions.FiniteStateMachineIterator
     end
 ```
 
-## Call definition
+## Caller definition
 
-A call function is constructed that creates the previously defined composite type. This function satisfy the calling convention of the original function definition and is returned from the macro:
+A caller function is constructed that creates the previously defined composite type. This function satisfies the calling convention of the original function definition and is returned from the macro:
 
 ```julia
 function fibonacci(n::Int)
@@ -93,7 +99,7 @@ end
 
 ## Transformation of the body
 
-In 6 steps the body of the function definition is transformed into a finite state-machine.
+In 6 steps the body of the function definition is transformed into a finite state-machine:
 
 ### Renaming of slots
 
@@ -104,11 +110,12 @@ begin
   _fsmi.a = 0
   _fsmi.b = 1
   _fsmi._iter = 1:n-1
-  _fsmi._iterstate = start(_fsmi._iter)
-  while !done(_fsmi._iter, _fsmi._iterstate)
-    _fsmi.i, _fsmi._iterstate = next(_fsmi._iter, _fsmi._iterstate)
+  state = iterate(_fsmi._iter)
+  while state !== nothing
+    _fsmi.i, _fsmi._iterstate = state
     @yield _fsmi.a
     _fsmi.a, _fsmi.b = _fsmi.b, _fsmi.a + _fsmi.b
+    state = iterate(_fsmi._iter, _fsmi._iterstate)
   end
   _fsmi.a
 end
@@ -132,76 +139,79 @@ begin
   _fsmi.a = 0
   _fsmi.b = 1
   _fsmi._iter = 1:n-1
-  _fsmi._iterstate = start(_fsmi._iter)
-  while !done(_fsmi._iter, _fsmi._iterstate)
-    _fsmi.i, _fsmi._iterstate = next(_fsmi._iter, _fsmi._iterstate)
+  state = iterate(_fsmi._iter)
+  while state !== nothing
+    _fsmi.i, _fsmi._iterstate = state
     @yield _fsmi.a
     _arg isa Exception && throw(_arg)
     _fsmi.a, _fsmi.b = _fsmi.b, _fsmi.a + _fsmi.b
+    state = iterate(_fsmi._iter, _fsmi._iterstate)
   end
   _fsmi.a
 end
 ```
 
 ### Try catch finally end block handling
 
-`try`-`catch`-`finally`-`end` expressions are converted in a sequence of `try`-`catch`-`end` expressions with at the end of the `catch` part a non local jump to a label that marks the beginning of the expressions in the `finally` part.
+`try`-`catch`-`finally`-`end` expressions are converted into a sequence of `try`-`catch`-`end` expressions; at the end of the `catch` part, a non-local jump is inserted to a label that marks the beginning of the expressions in the `finally` part.
 
 ### Yield transformation
 
-The `@yield` statement is replaced by a `return` statement and a label placeholder as endpoint of a non local jump:
+The `@yield` statement is replaced by a `return` statement and a label placeholder as target of a non-local jump:
 
 ```julia
 begin
   _fsmi.a = 0
   _fsmi.b = 1
   _fsmi._iter = 1:n-1
-  _fsmi._iterstate = start(_fsmi._iter)
-  while !done(_fsmi._iter, _fsmi._iterstate)
-    _fsmi.i, _fsmi._iterstate = next(_fsmi._iter, _fsmi._iterstate)
+  state = iterate(_fsmi._iter)
+  while state !== nothing
+    _fsmi.i, _fsmi._iterstate = state
     _fsmi._state = 0x01
     return _fsmi.a
     @label _STATE_1
     _fsmi._state = 0xff
     _arg isa Exception && throw(_arg)
     _fsmi.a, _fsmi.b = _fsmi.b, _fsmi.a + _fsmi.b
+    state = iterate(_fsmi._iter, _fsmi._iterstate)
   end
   _fsmi.a
 end
 ```
 
 ### Dispatch mechanism
 
-A dispatch mechanism is inserted at the start of the body to allow a non local jump to a label inside the body:
+A dispatch mechanism is inserted at the start of the body to allow a non-local jump to a label inside the body:
 
 ```julia
 begin
-  _fsmi_state == 0x00 && @goto _STATE_0
-  _fsmi_state == 0x01 && @goto _STATE_1
+  _fsmi._state == 0x00 && @goto _STATE_0
+  _fsmi._state == 0x01 && @goto _STATE_1
   error("@resumable function has stopped!")
   @label _STATE_0
   _fsmi._state = 0xff
   _arg isa Exception && throw(_arg)
   _fsmi.a = 0
   _fsmi.b = 1
   _fsmi._iter = 1:n-1
-  _fsmi._iterstate = start(_fsmi._iter)
-  while !done(_fsmi._iter, _fsmi._iterstate)
-    _fsmi.i, _fsmi._iterstate = next(_fsmi._iter, _fsmi._iterstate)
+  state = iterate(_fsmi._iter)
+  while state !== nothing
+    _fsmi.i, _fsmi._iterstate = state
     _fsmi._state = 0x01
     return _fsmi.a
     @label _STATE_1
     _fsmi._state = 0xff
     _arg isa Exception && throw(_arg)
     _fsmi.a, _fsmi.b = _fsmi.b, _fsmi.a + _fsmi.b
+    state = iterate(_fsmi._iter, _fsmi._iterstate)
   end
   _fsmi.a
 end
 ```
 
 ## Making the type callable
 
-A function is defined with one argument `_arg`:
+A function is defined with the above code as its body, accepting one argument `_arg`:
 
 ```julia
 function (_fsmi::##123)(_arg::Any=nothing)
@@ -214,15 +224,16 @@ function (_fsmi::##123)(_arg::Any=nothing)
   _fsmi.a = 0
   _fsmi.b = 1
   _fsmi._iter = 1:n-1
-  _fsmi._iterstate = start(_fsmi._iter)
-  while !done(_fsmi._iter, _fsmi._iterstate)
-    _fsmi.i, _fsmi._iterstate = next(_fsmi._iter, _fsmi._iterstate)
+  state = iterate(_fsmi._iter)
+  while state !== nothing
+    _fsmi.i, _fsmi._iterstate = state
     _fsmi._state = 0x01
     return _fsmi.a
     @label _STATE_1
     _fsmi._state = 0xff
     _arg isa Exception && throw(_arg)
     _fsmi.a, _fsmi.b = _fsmi.b, _fsmi.a + _fsmi.b
+    state = iterate(_fsmi._iter, _fsmi._iterstate)
   end
   _fsmi.a
 end

docs/src/manual.md

@@ -188,7 +188,7 @@ ERROR: @resumable function has stopped!
 DocTestSetup = nothing
 ```
 
-When the `@resumable function` returns normally an error will be thrown if called again.
+When the `@resumable function` returns normally (i.e. at the end of the function rather than at a `@yield` point), an error will be thrown if called again.
 
 ## Two-way communication
 
@@ -320,7 +320,7 @@ DocTestSetup = nothing
 
 ## Parametric `@resumable` functions
 
-Type parameters can be specified with a `where` clause:
+Type parameters can be specified with a normal Julia `where` clause:
 
 ```@meta
 DocTestSetup = quote
@@ -388,6 +388,7 @@ end
 @resumable function arrays_of_tuples()
   for u in [[(1,2),(3,4)], [(5,6),(7,8)]]
     for i in 1:2
+      local val
       let i=i
         val = [a[i] for a in u]
       end