Merge pull request #776 from gradha/pr_docs

Docstrings

lib/packages/docutils/rstgen.nim

@@ -688,7 +688,18 @@ proc formatNamedVars*(frmt: string, varnames: openarray[string],
 
 
 proc defaultConfig*(): PStringTable =
-  ## creates a default configuration for HTML generation.
+  ## Returns a default configuration for embedded HTML generation.
+  ##
+  ## The returned ``PStringTable`` contains the paramters used by the HTML
+  ## engine to build the final output. For information on what these parameters
+  ## are and their purpose, please look up the file ``config/nimdoc.cfg``
+  ## bundled with the compiler.
+  ##
+  ## The only difference between the contents of that file and the values
+  ## provided by this proc is the ``doc.file`` variable. The ``doc.file``
+  ## variable of the configuration file contains HTML to build standalone
+  ## pages, while this proc returns just the content for procs like
+  ## ``rstToHtml`` to generate the bare minimum HTML.
   result = newStringTable(modeStyleInsensitive)
   
   template setConfigVar(key, val: expr) =

lib/system.nim

@@ -2675,5 +2675,21 @@ proc locals*(): TObject {.magic: "Locals", noSideEffect.} =
   ## in the current scope. This is quite fast as it does not rely
   ## on any debug or runtime information. Note that in constrast to what
   ## the official signature says, the return type is not ``TObject`` but a
-  ## tuple of a structure that depends on the current scope.
+  ## tuple of a structure that depends on the current scope. Example:
+  ##
+  ## .. code-block:: nimrod
+  ##   proc testLocals() =
+  ##     var
+  ##       a = "something"
+  ##       b = 4
+  ##       c = locals()
+  ##       d = "super!"
+  ##
+  ##     b = 1
+  ##     for name, value in fieldPairs(c):
+  ##       echo "name ", name, " with value ", value
+  ##     echo "B is ", b
+  ##   # -> name a with value something
+  ##   # -> name b with value 4
+  ##   # -> B is 1
   nil