better docs: os (#10492)

* better docs: os
* remove broken test on osx

lib/pure/includes/osenv.nim

@@ -102,9 +102,18 @@ proc findEnvVar(key: string): int =
 proc getEnv*(key: string, default = ""): TaintedString {.tags: [ReadEnvEffect].} =
   ## Returns the value of the `environment variable`:idx: named `key`.
   ##
-  ## If the variable does not exist, "" is returned. To distinguish
+  ## If the variable does not exist, `""` is returned. To distinguish
-  ## whether a variable exists or it's value is just "", call
+  ## whether a variable exists or it's value is just `""`, call
-  ## `existsEnv(key)`.
+  ## `existsEnv(key) proc <#existsEnv,string>`_.
+  ##
+  ## See also:
+  ## * `existsEnv proc <#existsEnv,string>`_
+  ## * `putEnv proc <#putEnv,string,string>`_
+  ## * `envPairs iterator <#envPairs.i>`_
+  runnableExamples:
+    assert getEnv("unknownEnv") == ""
+    assert getEnv("unknownEnv", "doesn't exist") == "doesn't exist"
+
   when nimvm:
     discard "built into the compiler"
   else:
@@ -119,6 +128,14 @@ proc getEnv*(key: string, default = ""): TaintedString {.tags: [ReadEnvEffect].}
 proc existsEnv*(key: string): bool {.tags: [ReadEnvEffect].} =
   ## Checks whether the environment variable named `key` exists.
   ## Returns true if it exists, false otherwise.
+  ##
+  ## See also:
+  ## * `getEnv proc <#getEnv,string,string>`_
+  ## * `putEnv proc <#putEnv,string,string>`_
+  ## * `envPairs iterator <#envPairs.i>`_
+  runnableExamples:
+    assert not existsEnv("unknownEnv")
+
   when nimvm:
     discard "built into the compiler"
   else:
@@ -127,7 +144,12 @@ proc existsEnv*(key: string): bool {.tags: [ReadEnvEffect].} =
 
 proc putEnv*(key, val: string) {.tags: [WriteEnvEffect].} =
   ## Sets the value of the `environment variable`:idx: named `key` to `val`.
-  ## If an error occurs, `EInvalidEnvVar` is raised.
+  ## If an error occurs, `OSError` is raised.
+  ##
+  ## See also:
+  ## * `getEnv proc <#getEnv,string,string>`_
+  ## * `existsEnv proc <#existsEnv,string>`_
+  ## * `envPairs iterator <#envPairs.i>`_
 
   # Note: by storing the string in the environment sequence,
   # we guarantee that we don't free the memory before the program
@@ -154,9 +176,15 @@ proc putEnv*(key, val: string) {.tags: [WriteEnvEffect].} =
         raiseOSError(osLastError())
 
 iterator envPairs*(): tuple[key, value: TaintedString] {.tags: [ReadEnvEffect].} =
-  ## Iterate over all `environments variables`:idx:. In the first component
+  ## Iterate over all `environments variables`:idx:.
-  ## of the tuple is the name of the current variable stored, in the second
+  ##
-  ## its value.
+  ## In the first component of the tuple is the name of the current variable stored,
+  ## in the second its value.
+  ##
+  ## See also:
+  ## * `getEnv proc <#getEnv,string,string>`_
+  ## * `existsEnv proc <#existsEnv,string>`_
+  ## * `putEnv proc <#putEnv,string,string>`_
   getEnvVarsC()
   for i in 0..high(environment):
     var p = find(environment[i], '=')

lib/pure/includes/oserr.nim

@@ -18,7 +18,7 @@ proc `$`*(err: OSErrorCode): string {.borrow.}
 proc osErrorMsg*(errorCode: OSErrorCode): string =
   ## Converts an OS error code into a human readable string.
   ##
-  ## The error code can be retrieved using the ``osLastError`` proc.
+  ## The error code can be retrieved using the `osLastError proc <#osLastError>`_.
   ##
   ## If conversion fails, or ``errorCode`` is ``0`` then ``""`` will be
   ## returned.
@@ -26,6 +26,16 @@ proc osErrorMsg*(errorCode: OSErrorCode): string =
   ## On Windows, the ``-d:useWinAnsi`` compilation flag can be used to
   ## make this procedure use the non-unicode Win API calls to retrieve the
   ## message.
+  ##
+  ## See also:
+  ## * `raiseOSError proc <#raiseOSError,OSErrorCode,string>`_
+  ## * `osLastError proc <#osLastError>`_
+  runnableExamples:
+    when defined(posix):
+      assert osErrorMsg(OSErrorCode(0)) == ""
+      assert osErrorMsg(OSErrorCode(1)) == "Operation not permitted"
+      assert osErrorMsg(OSErrorCode(2)) == "No such file or directory"
+
   result = ""
   when defined(nimscript):
     discard
@@ -48,13 +58,21 @@ proc osErrorMsg*(errorCode: OSErrorCode): string =
       result = $c_strerror(errorCode.int32)
 
 proc raiseOSError*(errorCode: OSErrorCode; additionalInfo = "") {.noinline.} =
-  ## Raises an ``OSError`` exception. The ``errorCode`` will determine the
+  ## Raises an `OSError exception <system.html#OSError>`_.
-  ## message, ``osErrorMsg`` will be used to get this message.
   ##
-  ## The error code can be retrieved using the ``osLastError`` proc.
+  ## The ``errorCode`` will determine the
+  ## message, `osErrorMsg proc <#osErrorMsg,OSErrorCode>`_ will be used
+  ## to get this message.
+  ##
+  ## The error code can be retrieved using the `osLastError proc
+  ## <#osLastError>`_.
   ##
   ## If the error code is ``0`` or an error message could not be retrieved,
   ## the message ``unknown OS error`` will be used.
+  ##
+  ## See also:
+  ## * `osErrorMsg proc <#osErrorMsg,OSErrorCode>`_
+  ## * `osLastError proc <#osLastError>`_
   var e: ref OSError; new(e)
   e.errorCode = errorCode.int32
   e.msg = osErrorMsg(errorCode)
@@ -80,6 +98,10 @@ proc osLastError*(): OSErrorCode {.sideEffect.} =
   ## On Windows some OS calls can reset the error code to ``0`` causing this
   ## procedure to return ``0``. It is therefore advised to call this procedure
   ## immediately after an OS call fails. On POSIX systems this is not a problem.
+  ##
+  ## See also:
+  ## * `osErrorMsg proc <#osErrorMsg,OSErrorCode>`_
+  ## * `raiseOSError proc <#raiseOSError,OSErrorCode,string>`_
   when defined(nimscript):
     discard
   elif defined(windows):

lib/pure/includes/osseps.nim

@@ -7,44 +7,44 @@ const
 when defined(Nimdoc): # only for proper documentation:
   const
     CurDir* = '.'
-      ## The constant string used by the operating system to refer to the
+      ## The constant character used by the operating system to refer to the
       ## current directory.
       ##
-      ## For example: '.' for POSIX or ':' for the classic Macintosh.
+      ## For example: `'.'` for POSIX or `':'` for the classic Macintosh.
 
     ParDir* = ".."
       ## The constant string used by the operating system to refer to the
       ## parent directory.
       ##
-      ## For example: ".." for POSIX or "::" for the classic Macintosh.
+      ## For example: `".."` for POSIX or `"::"` for the classic Macintosh.
 
     DirSep* = '/'
       ## The character used by the operating system to separate pathname
-      ## components, for example, '/' for POSIX or ':' for the classic
+      ## components, for example: `'/'` for POSIX, `':'` for the classic
-      ## Macintosh.
+      ## Macintosh, and `'\\'` on Windows.
 
     AltSep* = '/'
       ## An alternative character used by the operating system to separate
-      ## pathname components, or the same as `DirSep` if only one separator
+      ## pathname components, or the same as `DirSep <#DirSep>`_ if only one separator
-      ## character exists. This is set to '/' on Windows systems
+      ## character exists. This is set to `'/'` on Windows systems
-      ## where `DirSep` is a backslash.
+      ## where `DirSep <#DirSep>`_ is a backslash (`'\\'`).
 
     PathSep* = ':'
       ## The character conventionally used by the operating system to separate
-      ## search patch components (as in PATH), such as ':' for POSIX
+      ## search patch components (as in PATH), such as `':'` for POSIX
-      ## or ';' for Windows.
+      ## or `';'` for Windows.
 
     FileSystemCaseSensitive* = true
-      ## true if the file system is case sensitive, false otherwise. Used by
+      ## True if the file system is case sensitive, false otherwise. Used by
-      ## `cmpPaths` to compare filenames properly.
+      ## `cmpPaths proc <#cmpPaths,string,string>`_ to compare filenames properly.
 
     ExeExt* = ""
       ## The file extension of native executables. For example:
-      ## "" for POSIX, "exe" on Windows.
+      ## `""` for POSIX, `"exe"` on Windows (without a dot).
 
     ScriptExt* = ""
-      ## The file extension of a script file. For example: "" for POSIX,
+      ## The file extension of a script file. For example: `""` for POSIX,
-      ## "bat" on Windows.
+      ## `"bat"` on Windows.
 
     DynlibFormat* = "lib$1.so"
       ## The format string to turn a filename into a `DLL`:idx: file (also
@@ -127,4 +127,4 @@ else: # UNIX-like operating system
 const
   ExtSep* = '.'
     ## The character which separates the base filename from the extension;
-    ## for example, the '.' in ``os.nim``.
+    ## for example, the `'.'` in ``os.nim``.