Merge pull request #273 from gradha/pr_misc_documentation_improvements

Misc documentation improvements

4 files changed, 45 insertions, 5 deletions

diff --git a/lib/impure/web.nim b/lib/impure/web.nim
index 417fe9746..5f04422d1 100755
--- a/lib/impure/web.nim
+++ b/lib/impure/web.nim
@@ -17,7 +17,8 @@
 ## Currently only requesting URLs is implemented. The implementation depends

 ## on the libcurl library!

 ##

-## **Deprecated since version 0.8.8:** Use the ``httpclient`` module instead. 

+## **Deprecated since version 0.8.8:** Use the

+## `httpclient <httpclient.html>`_ module instead. 

 ## 

 

 {.deprecated.}

diff --git a/lib/pure/json.nim b/lib/pure/json.nim
index 941d88dfc..cee135f08 100755
--- a/lib/pure/json.nim
+++ b/lib/pure/json.nim
@@ -13,6 +13,23 @@
 ## (unlike XML). It is easy for machines to parse and generate.
 ## JSON is based on a subset of the JavaScript Programming Language,
 ## Standard ECMA-262 3rd Edition - December 1999.
+##
+## Usage example:
+##
+## .. code-block:: nimrod
+##  let
+##    small_json = """{"test": 1.3, "key2": true}"""
+##    jobj = parseJson(small_json)
+##  assert (jobj.kind == JObject)
+##  echo($jobj["test"].fnum)
+##  echo($jobj["key2"].bval)
+##
+## Results in:
+##
+## .. code-block:: nimrod
+##
+##   1.3000000000000000e+00
+##   true
 
 import 
   hashes, strutils, lexbase, streams, unicode
@@ -607,14 +624,14 @@ proc len*(n: PJsonNode): int =
   else: nil
 
 proc `[]`*(node: PJsonNode, name: String): PJsonNode =
-  ## Gets a field from a `JObject`.
+  ## Gets a field from a `JObject`. Returns nil if the key is not found.
   assert(node.kind == JObject)
   for key, item in items(node.fields):
     if key == name:
       return item
   return nil
   
-proc `[]`*(node: PJsonNode, index: Int): PJsonNode =
+proc `[]`*(node: PJsonNode, index: Int): PJsonNode {.raises: [EInvalidIndex].} =
   ## Gets the node at `index` in an Array.
   assert(node.kind == JArray)
   return node.elems[index]
@@ -893,6 +910,10 @@ when isMainModule:
   echo(parsed["keyÄÖöoßß"])
   echo()
   echo(pretty(parsed2))
+  try:
+    echo(parsed["key2"][12123])
+    raise newException(EInvalidValue, "That line was expected to fail")
+  except EInvalidIndex: echo()
 
   discard """
   while true:
diff --git a/lib/pure/streams.nim b/lib/pure/streams.nim
index 5db21d76a..212aab493 100755
--- a/lib/pure/streams.nim
+++ b/lib/pure/streams.nim
@@ -263,7 +263,8 @@ proc newFileStream*(f: TFile): PFileStream =
 
 proc newFileStream*(filename: string, mode: TFileMode): PFileStream = 
   ## creates a new stream from the file named `filename` with the mode `mode`.
-  ## If the file cannot be opened, nil is returned.
+  ## If the file cannot be opened, nil is returned. See the `system
+  ## <system.html>`_ module for a list of available TFileMode enums.
   var f: TFile
   if Open(f, filename, mode): result = newFileStream(f)
 
diff --git a/lib/pure/strutils.nim b/lib/pure/strutils.nim
index 0f11b4d89..8a5061037 100755
--- a/lib/pure/strutils.nim
+++ b/lib/pure/strutils.nim
@@ -186,7 +186,24 @@ iterator split*(s: string, seps: set[char] = Whitespace): string =
   ##   for word in split(";;this;is;an;;example;;;", {';'}):

   ##     writeln(stdout, word)

   ##

-  ## produces the same output.

+  ## 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"

+  ##

   var last = 0

   assert(not ('\0' in seps))

   while last < len(s):