better documentation for 'finished' for first class iterators

doc/manual/procs.txt

@@ -556,6 +556,40 @@ The builtin ``system.finished`` can be used to determine if an iterator has
 finished its operation; no exception is raised on an attempt to invoke an
 iterator that has already finished its work.
 
+Note that ``system.finished`` is error prone to use because it only returns
+``true`` one iteration after the iterator has finished:
+
+.. code-block:: nim
+  iterator mycount(a, b: int): int {.closure.} =
+    var x = a
+    while x <= b:
+      yield x
+      inc x
+
+  var c = mycount # instantiate the iterator
+  while not finished(c):
+    echo c(1, 3)
+
+  # Produces
+  1
+  2
+  3
+  0
+
+Instead this code has be used:
+
+.. code-block:: nim
+  var c = mycount # instantiate the iterator
+  while true:
+    let value = c(1, 3)
+    if finished(c): break # and discard 'value'!
+    echo value
+
+It helps to think that the iterator actually returns a
+pair ``(value, done)`` and ``finished`` is used to access the hidden ``done``
+field.
+
+
 Closure iterators are *resumable functions* and so one has to provide the
 arguments to every call. To get around this limitation one can capture
 parameters of an outer factory proc:

doc/manual/types.txt

@@ -681,6 +681,23 @@ dereferencing operations for reference types:
   n.data = 9
   # no need to write n[].data; in fact n[].data is highly discouraged!
 
+Automatic dereferencing is also performed for the first argument of a routine
+call. But currently this feature has to be only enabled
+via ``{.experimental.}``:
+
+.. code-block:: nim
+  {.experimental.}
+
+  proc depth(x: NodeObj): int = ...
+
+  var
+    n: Node
+  new(n)
+  echo n.depth
+  # no need to write n[].depth either
+  
+
+
 In order to simplify structural type checking, recursive tuples are not valid:
 
 .. code-block:: nim

todo.txt

@@ -1,7 +1,6 @@
 version 0.10
 ============
 
-- document the 'finished' gotcha
 - improve the docs for inheritance
 - The bitwise 'not' operator will be renamed to 'bnot' to
   prevent 'not 4 == 5' from compiling. -> requires 'mixin' annotation for procs!
@@ -50,8 +49,6 @@ Bugs
 version 0.9.x
 =============
 
-- implicit deref for parameter matching; but only for  x.f(a, b) --> looks like
-  a nice compromise
 - overloading of '='
 - allow simple read accesses to global variables --> difficult to ensure that
   no data races happen

web/news.txt

@@ -27,6 +27,9 @@ News
 
   - For empty ``case object`` branches ``discard`` can finally be used instead
     of ``nil``.
+  - Automatic dereferencing is now done for the first argument of a routine
+    call if overloading resolution produces no match otherwise. This feature
+    has to be enabled with the `experimental`_ pragma.
 
 
 2014-12-29 Version 0.10.2 released