Merge pull request #1107 from ReneSac/devel

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
@@ -150,6 +150,18 @@ the syntax, watch their indentation:
 **Note**: To comment out a large piece of code, it is often better to use a
 ``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 +587,46 @@ 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
+A procedure that returns a value has an implicit ``result`` variable declared 
-represents the return value. A ``return`` statement with no expression is a
+that represents the return value. A ``return`` statement with no expression is a
-shorthand for ``return result``. So all three code snippets are equivalent:
+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
+  proc sumTillNegative(x: varargs[int]): int = 
-
+    for i in x:
-.. code-block:: nimrod
+      if i < 0:
-  result = 42
+        return
-  return
+      result = result + i  
-
+      
-.. code-block:: nimrod
+  echo sumTillNegative() # echos 0
-  result = 42
+  echo sumTillNegative(3, 4, 5) # echos 12
-  return result
+  echo sumTillNegative(3, 4 , -1 , 6) # echos 7
 
+The ``result`` variable is already implicitly declared at the start of the 
+function, so declaring it again with 'var result', for example, would shadow it
+with a normal variable of the same name. The result variable is also already
+initialised with the type's default value. Note that referential data types will
+be ``nil`` at the start of the procedure, and thus may require manual
+initialisation.
 
+      
 Parameters
 ----------
-Parameters are constant in the procedure body. Their value cannot be changed
+Parameters are constant in the procedure body. By default, their value cannot be
-because this allows the compiler to implement parameter passing in the most
+changed because this allows the compiler to implement parameter passing in the 
-efficient way. If the procedure needs to modify the argument for 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 +665,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
 ---------------