Add os module documentation. Fix some fiber documentation.

src/core/fiber.c

@@ -481,7 +481,7 @@ static const JanetReg cfuns[] = {
         "\t:pending - the fiber has been yielded\n"
         "\t:user(0-9) - the fiber is suspended by a user signal\n"
         "\t:alive - the fiber is currently running and cannot be resumed\n"
-        "\t:new - the fiber has just been created and not yet run\n"
+        "\t:new - the fiber has just been created and not yet run"
     },
     {"fiber.stack", cfun_stack, 
         "(fiber.stack fib)\n\n"
@@ -496,7 +496,7 @@ static const JanetReg cfuns[] = {
         "\t:name - the human friendly name of the function\n"
         "\t:pc - integer indicating the location of the program counter\n"
         "\t:source - string with filename or other identifier for the source code\n"
-        "\t:tail - boolean indicating a tail call\n"
+        "\t:tail - boolean indicating a tail call"
     },
     {"fiber.current", cfun_current, 
         "(fiber.current)\n\n"

src/core/os.c

@@ -129,27 +129,16 @@ static int os_execute(JanetArgs args) {
     argv[args.n] = NULL;
 
     /* Fork child process */
-    pid_t pid;
+    pid_t pid = fork();
-    if (0 == (pid = fork())) {
+    if (pid < 0) {
+        JANET_THROW(args, "failed to execute");
+    } else if (pid == 0) {
         if (-1 == execve((const char *)argv[0], (char **)argv, NULL)) {
             exit(1);
         }
     }
-
-    /* Wait for child process */
     int status;
-    struct timespec waiter;
+    waitpid(pid, &status, 0);
-    waiter.tv_sec = 0;
-    waiter.tv_nsec = 200;
-    while (0 == waitpid(pid, &status, WNOHANG)) {
-        waiter.tv_nsec = (waiter.tv_nsec * 3) / 2;
-        /* Keep increasing sleep time by a factor of 3/2
-         * until a maximum */
-        if (waiter.tv_nsec > 4999999)
-            waiter.tv_nsec = 5000000;
-        nanosleep(&waiter, NULL);
-    }
-
     JANET_RETURN_INTEGER(args, status);
 }
 #endif
@@ -294,16 +283,55 @@ static int os_cwd(JanetArgs args) {
 }
 
 static const JanetReg cfuns[] = {
-    {"os.which", os_which, NULL},
+    {"os.which", os_which, 
-    {"os.execute", os_execute, NULL},
+        "(os.which)\n\n"
-    {"os.shell", os_shell, NULL},
+        "Check the current operating system. Returns one of:\n\n"
-    {"os.exit", os_exit, NULL},
+        "\t:windows - Microsoft Windows\n"
-    {"os.getenv", os_getenv, NULL},
+        "\t:macos - Apple macos\n"
-    {"os.setenv", os_setenv, NULL},
+        "\t:posix - A POSIX compatible system (default)"
-    {"os.time", os_time, NULL},
+    },
-    {"os.clock", os_clock, NULL},
+    {"os.execute", os_execute, 
-    {"os.sleep", os_sleep, NULL},
+        "(os.execute program & args)\n\n"
-    {"os.cwd", os_cwd, NULL},
+        "Execute a program on the system and pass it string arguments. Returns "
+        "the exit status of the program."
+    },
+    {"os.shell", os_shell, 
+        "(os.shell str)\n\n"
+        "Pass a command string str directly to the system shell."
+    },
+    {"os.exit", os_exit, 
+        "(os.exit x)\n\n"
+        "Exit from janet with an exit code equal to x. If x is not an integer, "
+        "the exit with status equal the hash of x."
+    },
+    {"os.getenv", os_getenv, 
+        "(os.getenv variable)\n\n"
+        "Get the string value of an environment variable."
+    },
+    {"os.setenv", os_setenv, 
+        "(os.setenv variable value)\n\n"
+        "Set an environment variable."
+    },
+    {"os.time", os_time, 
+        "(os.time)\n\n"
+        "Get the current time expressed as the number of seconds since "
+        "January 1, 1970, the Unix epoch. Returns a real number."
+    },
+    {"os.clock", os_clock, 
+        "(os.clock)\n\n"
+        "Return the number of seconds since some fixed point in time. The clock "
+        "is guaranteed to be non decreased in real time."
+    },
+    {"os.sleep", os_sleep, 
+        "(os.sleep nsec)\n\n"
+        "Suspend the program for nsec seconds. 'nsec' can be a real number. Returns "
+        "nil."
+        
+    },
+    {"os.cwd", os_cwd, 
+        "(os.cwd)\n\n"
+        "Returns the current working directory."
+    },
     {NULL, NULL, NULL}
 };