Merge pull request #524 from gradha/pr_misc_docs

Miscellaneous doc tweaks

lib/impure/re.nim

@@ -201,7 +201,10 @@ proc find*(s: string, pattern: TRegEx, start = 0): int =
   return rawMatches[0]
   
 iterator findAll*(s: string, pattern: TRegEx, start = 0): string = 
-  ## yields all matching *substrings* of `s` that match `pattern`.
+  ## Yields all matching *substrings* of `s` that match `pattern`.
+  ##
+  ## Note that since this is an iterator you should not modify the string you
+  ## are iterating over: bad things could happen.
   var i = int32(start)
   var rawMatches: array[0..maxSubpatterns * 3 - 1, cint]
   while true:

lib/pure/os.nim

@@ -474,8 +474,17 @@ proc JoinPath*(head, tail: string): string {.
   ## .. code-block:: nimrod
   ##   "usr/lib"
   ##
-  ## If head is the empty string, tail is returned.
-  ## If tail is the empty string, head is returned.
+  ## If head is the empty string, tail is returned. If tail is the empty
+  ## string, head is returned with a trailing path separator. If tail starts
+  ## with a path separator it will be removed when concatenated to head. Other
+  ## path separators not located on boundaries won't be modified. More
+  ## examples on Unix:
+  ##
+  ## .. code-block:: nimrod
+  ##   assert JoinPath("usr", "") == "usr/"
+  ##   assert JoinPath("", "lib") == "lib"
+  ##   assert JoinPath("", "/lib") == "/lib"
+  ##   assert JoinPath("usr/", "/lib") == "usr/lib"
   if len(head) == 0:
     result = tail
   elif head[len(head)-1] in {DirSep, AltSep}:
@@ -491,15 +500,24 @@ proc JoinPath*(head, tail: string): string {.
 
 proc JoinPath*(parts: varargs[string]): string {.noSideEffect,
   rtl, extern: "nos$1OpenArray".} =
-  ## The same as `JoinPath(head, tail)`, but works with any number
-  ## of directory parts.
+  ## The same as `JoinPath(head, tail)`, but works with any number of directory
+  ## parts. You need to pass at least one element or the proc will assert in
+  ## debug builds and crash on release builds.
   result = parts[0]
   for i in 1..high(parts):
     result = JoinPath(result, parts[i])
 
 proc `/` * (head, tail: string): string {.noSideEffect.} =
-  ## The same as ``joinPath(head, tail)``
-  return joinPath(head, tail)
+  ## The same as ``JoinPath(head, tail)``
+  ##
+  ## Here are some examples for Unix:
+  ##
+  ## .. code-block:: nimrod
+  ##   assert "usr" / "" == "usr/"
+  ##   assert "" / "lib" == "lib"
+  ##   assert "" / "/lib" == "/lib"
+  ##   assert "usr/" / "/lib" == "usr/lib"
+  return JoinPath(head, tail)
 
 proc SplitPath*(path: string): tuple[head, tail: string] {.
   noSideEffect, rtl, extern: "nos$1".} =
@@ -814,8 +832,13 @@ proc sameFileContent*(path1, path2: string): bool {.rtl, extern: "nos$1",
 
 proc copyFile*(source, dest: string) {.rtl, extern: "nos$1", 
   tags: [FReadIO, FWriteIO].} =
-  ## Copies a file from `source` to `dest`. If this fails,
-  ## `EOS` is raised.
+  ## Copies a file from `source` to `dest`.
+  ##
+  ## If this fails, `EOS` is raised. On the Windows platform this proc will
+  ## copy the source file's attributes into dest. On other platforms you need
+  ## to use getFilePermissions and setFilePermissions to copy them by hand,
+  ## otherwise `dest` will inherit the default permissions of a newly created
+  ## file for the user.
   when defined(Windows):
     when useWinUnicode:
       let s = newWideCString(source)
@@ -1498,7 +1521,7 @@ proc getAppFilename*(): string {.rtl, extern: "nos$1", tags: [FReadIO].} =
       if len(result) > 0 and result[0] != DirSep: # not an absolute path?
         # iterate over any path in the $PATH environment variable
         for p in split(string(getEnv("PATH")), {PathSep}):
-          var x = joinPath(p, result)
+          var x = JoinPath(p, result)
           if ExistsFile(x): return x
 
 proc getApplicationFilename*(): string {.rtl, extern: "nos$1", deprecated.} =

lib/pure/parseutils.nim

@@ -27,8 +27,24 @@ proc toLower(c: char): char {.inline.} =
 
 proc parseHex*(s: string, number: var int, start = 0): int {.
   rtl, extern: "npuParseHex", noSideEffect.}  = 
-  ## parses a hexadecimal number and stores its value in ``number``. Returns
-  ## the number of the parsed characters or 0 in case of an error.
+  ## Parses a hexadecimal number and stores its value in ``number``.
+  ##
+  ## Returns the number of the parsed characters or 0 in case of an error. This
+  ## proc is sensitive to the already existing value of ``number`` and will
+  ## likely not do what you want unless you make sure ``number`` is zero. You
+  ## can use this feature to *chain* calls, though the result int will quickly
+  ## overflow. Example:
+  ##
+  ## .. code-block:: nimrod
+  ##   var value = 0
+  ##   discard parseHex("0x38", value)
+  ##   assert value == 56
+  ##   discard parseHex("0x34", value)
+  ##   assert value == 56 * 256 + 52
+  ##   value = -1
+  ##   discard parseHex("0x38", value)
+  ##   assert value == -200
+  ##
   var i = start
   var foundDigit = false
   if s[i] == '0' and (s[i+1] == 'x' or s[i+1] == 'X'): inc(i, 2)
@@ -383,6 +399,14 @@ iterator interpolatedFragments*(s: string): tuple[kind: TInterpolatedKind,
 when isMainModule:
   for k, v in interpolatedFragments("$test{}  $this is ${an{  example}}  "):
     echo "(", k, ", \"", v, "\")"
+  var value = 0
+  discard parseHex("0x38", value)
+  assert value == 56
+  discard parseHex("0x34", value)
+  assert value == 56 * 256 + 52
+  value = -1
+  discard parseHex("0x38", value)
+  assert value == -200
 
 
 {.pop.}