Merge pull request #426 from gradha/pr_misc_doc_improvements

Misc doc improvements

lib/pure/strutils.nim

@@ -166,27 +166,32 @@ proc toOctal*(c: char): string {.noSideEffect, rtl, extern: "nsuToOctal".} =
     val = val div 8
 
 iterator split*(s: string, seps: set[char] = Whitespace): string =
-  ## Splits the string `s` into substrings.
+  ## Splits the string `s` into substrings using a group of separators.
   ##
-  ## Substrings are separated by a substring containing only `seps`.
+  ## Substrings are separated by a substring containing only `seps`. Note
-  ## Examples:
+  ## that whole sequences of characters found in ``seps`` will be counted as
+  ## a single split point and leading/trailing separators will be ignored.
+  ## The following example:
   ##
   ## .. code-block:: nimrod
   ##   for word in split("  this is an  example  "):
   ##     writeln(stdout, word)
   ##
-  ## Results in:
+  ## ...generates this output:
   ##
-  ## .. code-block:: nimrod
+  ## .. code-block::
   ##   "this"
   ##   "is"
   ##   "an"
   ##   "example"
   ##
+  ## And the following code:
+  ##
+  ## .. code-block:: nimrod
   ##   for word in split(";;this;is;an;;example;;;", {';'}):
   ##     writeln(stdout, word)
   ##
-  ## produces the same output. The code:
+  ## ...produces the same output as the first example. The code:
   ##
   ## .. code-block:: nimrod
   ##   let date = "2012-11-20T22:08:08.398990"
@@ -194,9 +199,9 @@ iterator split*(s: string, seps: set[char] = Whitespace): string =
   ##   for number in split(date, separators):
   ##     writeln(stdout, number)
   ##
-  ## Results in:
+  ## ...results in:
   ##
-  ## .. code-block:: nimrod
+  ## .. code-block::
   ##   "2012"
   ##   "11"
   ##   "20"
@@ -214,10 +219,12 @@ iterator split*(s: string, seps: set[char] = Whitespace): string =
       yield substr(s, first, last-1)
 
 iterator split*(s: string, sep: char): string =
-  ## Splits the string `s` into substrings.
+  ## Splits the string `s` into substrings using a single separator.
   ##
   ## Substrings are separated by the character `sep`.
-  ## Example:
+  ## Unlike the version of the iterator which accepts a set of separator
+  ## characters, this proc will not coalesce groups of the
+  ## separator, returning a string for each found character. The code:
   ##
   ## .. code-block:: nimrod
   ##   for word in split(";;this;is;an;;example;;;", ';'):
@@ -225,7 +232,7 @@ iterator split*(s: string, sep: char): string =
   ##
   ## Results in:
   ##
-  ## .. code-block:: nimrod
+  ## .. code-block::
   ##   ""
   ##   ""
   ##   "this"

lib/system.nim

@@ -909,12 +909,17 @@ var programResult* {.exportc: "nim_program_result".}: int
 
 proc quit*(errorcode: int = QuitSuccess) {.
   magic: "Exit", importc: "exit", noDecl, noReturn.}
-  ## stops the program immediately; before stopping the program the
+  ## Stops the program immediately with an exit code.
-  ## "quit procedures" are called in the opposite order they were added
+  ##
-  ## with ``addQuitProc``. ``quit`` never returns and ignores any
+  ## Before stopping the program the "quit procedures" are called in the
-  ## exception that may have been raised by the quit procedures.
+  ## opposite order they were added with ``addQuitProc``. ``quit`` never
-  ## It does *not* call the garbage collector to free all the memory,
+  ## returns and ignores any exception that may have been raised by the quit
-  ## unless a quit procedure calls ``GC_collect``.
+  ## procedures.  It does *not* call the garbage collector to free all the
+  ## memory, unless a quit procedure calls ``GC_collect``.
+  ##
+  ## The proc ``quit(QuitSuccess)`` is called implicitly when your nimrod
+  ## program finishes without incident. A raised unhandled exception is
+  ## equivalent to calling ``quit(QuitFailure)``.
 
 template sysAssert(cond: bool, msg: string) =
   when defined(useSysAssert):

lib/system/threads.nim

@@ -14,8 +14,8 @@
 ## Nimrod's memory model for threads is quite different from other common 
 ## programming languages (C, Pascal): Each thread has its own
 ## (garbage collected) heap and sharing of memory is restricted. This helps
-## to prevent race conditions and improves efficiency. See the manual for
+## to prevent race conditions and improves efficiency. See `the manual for
-## details of this memory model.
+## details of this memory model <manual.html#threads>`_.
 ##
 ## Example:
 ##