Additions and clarifications to tutorial 1.

doc/tut1.txt

@@ -132,7 +132,7 @@ a backslash:
     TMyObject {.final, pure, acyclic.} = object  # comment continues: \
       # we have lots of space here to comment 'TMyObject'.
       # This line belongs to the comment as it's properly aligned.
-
+
 
 Comments are tokens; they are only allowed at certain places in the input file
 as they belong to the syntax tree! This feature enables perfect source-to-source
@@ -148,7 +148,20 @@ the syntax, watch their indentation:
     # comment has not the correct indentation level -> syntax error!
 
 **Note**: To comment out a large piece of code, it is often better to use a
-``when false:`` statement.
+``when false:`` statement. 
+
+.. code-block:: nimrod
+  when false:
+    brokenCode()
+    
+Another option is to use the `discard`_ statement together with
+*long string literals* to create block comments:
+
+.. code-block:: nimrod
+  discard """ You can have any nimrod code text commented 
+  out inside this with no indentation restrictions.
+        yes("May I ask a pointless question?") """
+        
 
 
 Numbers
@@ -575,27 +588,44 @@ Some terminology: in the example ``question`` is called a (formal) *parameter*,
 
 Result variable
 ---------------
-A procedure that returns a value has an implicit ``result`` variable that
-represents the return value. A ``return`` statement with no expression is a
-shorthand for ``return result``. So all three code snippets are equivalent:
+A procedure that returns a value has an implicit ``result`` variable declared 
+that represents the return value. A ``return`` statement with no expression is a
+shorthand for ``return result``. The ``result`` value is always returned 
+automatically at the end a procedure if there is no ``return`` statement at
+the exit.
 
 .. code-block:: nimrod
-  return 42
-
-.. code-block:: nimrod
-  result = 42
-  return
-
-.. code-block:: nimrod
-  result = 42
-  return result
+  proc sumTillNegative(x: varargs[int]): int = 
+    for i in x:
+      if i < 0:
+        return
+      result = result + i  
+      
+  echo sumTillNegative() # echos 0
+  echo sumTillNegative(3, 4, 5) # echos 12
+  echo sumTillNegative(3, 4 , -1 , 6) # echos 7
 
+The ``result`` variable is already implicitly declared at the start of the 
+function and initialised with the type's default value, so declaring it again 
+with 'var return', for example, would shadow it with a normal variable of the
+same name.
 
+      
 Parameters
 ----------
-Parameters are constant in the procedure body. Their value cannot be changed
-because this allows the compiler to implement parameter passing in the most
-efficient way. If the procedure needs to modify the argument for the
+Parameters are constant in the procedure body. By default, their value cannot be
+changed because this allows the compiler to implement parameter passing in the 
+most efficient way. If a mutable variable is needed inside the procedure, it has
+to be declared with ``var`` in the procedure body. Shadowing the parameter name
+is possible, and actually an idiom: 
+
+.. code-block:: nimrod
+  proc printSeq(s: seq, nprinted: int = -1) =
+    var nprinted = if nprinted == -1: s.len else: min(nprinted, s.len)
+    for i in 0 .. <nprinted:
+      echo s[i]
+    
+If the procedure needs to modify the argument for the
 caller, a ``var`` parameter can be used:
 
 .. code-block:: nimrod
@@ -634,6 +664,9 @@ been declared with the ``discardable`` pragma:
     
   p(3, 4) # now valid
 
+The discard statement can also be used to create block comments as described
+in the `Comments`_.
+
 
 Named arguments
 ---------------