Merge pull request #426 from gradha/pr_misc_doc_improvements

Misc doc improvements

lib/pure/strutils.nim

@@ -165,45 +165,50 @@ proc toOctal*(c: char): string {.noSideEffect, rtl, extern: "nsuToOctal".} =
     result[i] = Chr(val mod 8 + ord('0'))
     val = val div 8
 
-iterator split*(s: string, seps: set[char] = Whitespace): string =
-  ## Splits the string `s` into substrings.
-  ##
-  ## Substrings are separated by a substring containing only `seps`.
-  ## Examples:
-  ##
-  ## .. code-block:: nimrod
-  ##   for word in split("  this is an  example  "):
-  ##     writeln(stdout, word)
-  ##
-  ## Results in:
-  ##
-  ## .. code-block:: nimrod
-  ##   "this"
-  ##   "is"
-  ##   "an"
-  ##   "example"
-  ##
-  ##   for word in split(";;this;is;an;;example;;;", {';'}):
-  ##     writeln(stdout, word)
-  ##
-  ## produces the same output. The code:
-  ##
-  ## .. code-block:: nimrod
-  ##   let date = "2012-11-20T22:08:08.398990"
-  ##   let separators = {' ', '-', ':', 'T'}
-  ##   for number in split(date, separators):
-  ##     writeln(stdout, number)
-  ##
-  ## Results in:
-  ##
-  ## .. code-block:: nimrod
-  ##   "2012"
-  ##   "11"
-  ##   "20"
-  ##   "22"
-  ##   "08"
-  ##   "08.398990"
-  ##
+iterator split*(s: string, seps: set[char] = Whitespace): string =
+  ## Splits the string `s` into substrings using a group of separators.
+  ##
+  ## Substrings are separated by a substring containing only `seps`. Note
+  ## 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)
+  ##
+  ## ...generates this output:
+  ##
+  ## .. 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 as the first example. The code:
+  ##
+  ## .. code-block:: nimrod
+  ##   let date = "2012-11-20T22:08:08.398990"
+  ##   let separators = {' ', '-', ':', 'T'}
+  ##   for number in split(date, separators):
+  ##     writeln(stdout, number)
+  ##
+  ## ...results in:
+  ##
+  ## .. code-block::
+  ##   "2012"
+  ##   "11"
+  ##   "20"
+  ##   "22"
+  ##   "08"
+  ##   "08.398990"
+  ##
   var last = 0
   assert(not ('\0' in seps))
   while last < len(s):
@@ -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
-  ## "quit procedures" are called in the opposite order they were added
-  ## with ``addQuitProc``. ``quit`` never returns and ignores any
-  ## exception that may have been raised by the quit procedures.
-  ## It does *not* call the garbage collector to free all the memory,
-  ## unless a quit procedure calls ``GC_collect``.
+  ## Stops the program immediately with an exit code.
+  ##
+  ## Before stopping the program the "quit procedures" are called in the
+  ## opposite order they were added with ``addQuitProc``. ``quit`` never
+  ## returns and ignores any exception that may have been raised by the quit
+  ## 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
-## details of this memory model.
+## to prevent race conditions and improves efficiency. See `the manual for
+## details of this memory model <manual.html#threads>`_.
 ##
 ## Example:
 ##