add descriptions of sys_wait constants, macros and functions

src/header/sys_wait/cbindgen.toml

@@ -10,13 +10,21 @@ after_includes = """
 #include <bits/id-t.h>  // for id_t from sys/types.h
 #include <bits/pid-t.h> // for pid_t from sys/types.h
 
+// Return exit status.
 #define WEXITSTATUS(s) (((s) >> 8) & 0xff)
+// Return signal number that caused process to terminate.
 #define WTERMSIG(s) ((s) & 0x7f)
+// Return signal number that caused process to stop.
 #define WSTOPSIG(s) WEXITSTATUS(s)
+// True if WIFSIGNALED was true and creation of a core image was attempted.
 #define WCOREDUMP(s) (((s) & 0x80) != 0)
+// True if child exited normally.
 #define WIFEXITED(s) (((s) & 0x7f) == 0)
+// True if child stopped due to uncaught signal.
 #define WIFSTOPPED(s) (((s) & 0xff) == 0x7f)
+// True if child exited due to uncaught signal.
 #define WIFSIGNALED(s) (((((s) & 0x7f) + 1U) & 0x7f) >= 2) // Ends with 1111111 or 10000000
+// True if child has been continued.
 #define WIFCONTINUED(s) ((s) == 0xffff)
 """
 language = "C"

src/header/sys_wait/mod.rs

@@ -11,20 +11,44 @@ use crate::{
     },
 };
 
+/// Do not hang if no status is available; return immediately.
 pub const WNOHANG: c_int = 1;
+/// Report status of stopped child process.
 pub const WUNTRACED: c_int = 2;
-
-pub const WSTOPPED: c_int = 2;
-pub const WEXITED: c_int = 4;
+/// Report status of continued child process.
 pub const WCONTINUED: c_int = 8;
+
+/// Status is returned for any child that has stopped upon receipt of a signal.
+pub const WSTOPPED: c_int = 2;
+/// Wait for processes that have terminated.
+pub const WEXITED: c_int = 4;
+/// Keep the process whose status is returned in `infop` in a waitable state.
 pub const WNOWAIT: c_int = 0x0100_0000;
 
+/// Non-POSIX, see <https://www.man7.org/linux/man-pages/man2/waitpid.2.html>.
+///
+/// Do not wait for children of other threads in the same thread group.
 pub const __WNOTHREAD: c_int = 0x2000_0000;
+/// Non-POSIX, see <https://www.man7.org/linux/man-pages/man2/waitpid.2.html>.
+///
+/// Wait for all children regardless of type ("clone" or "non-clone").
 pub const __WALL: c_int = 0x4000_0000;
+/// Non-POSIX, see <https://www.man7.org/linux/man-pages/man2/waitpid.2.html>.
+///
+/// Wait for "clone" children only.
 #[allow(overflowing_literals)]
 pub const __WCLONE: c_int = 0x8000_0000;
 
 /// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/wait.html>.
+///
+/// Obtains status information pertaining to one of the caller's child
+/// processes.
+///
+/// If returning because the status of a child process is available, returns a
+/// value equal to the process ID of the child process for which status is
+/// reported. If returning due to the delivery of a signal to the calling
+/// process, returns `-1` and sets errno to `EINTR`. If otherwise failing,
+/// returns `-1` and sets errno.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn wait(stat_loc: *mut c_int) -> pid_t {
     unsafe { waitpid(!0, stat_loc, 0) }
@@ -45,6 +69,18 @@ pub unsafe extern "C" fn wait(stat_loc: *mut c_int) -> pid_t {
  */
 
 /// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/waitpid.html>.
+///
+/// Obtains status information pertaining to one of the caller's child
+/// processes.
+///
+/// If returning because the status of a child process is available, returns a
+/// value equal to the process ID of the child process for which status is
+/// reported. If returning due to the delivery of a signal to the calling
+/// process, returns `-1` and sets errno to `EINTR`. if invoked with `WNOHANG`
+/// set in `options`, it has at least one child process specified by `pid` for
+/// wchich status is not available, and status is not available for any process
+/// specified by `pid`, `0` is returned. If otherwise failing, returns `-1` and
+/// sets errno.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn waitpid(pid: pid_t, stat_loc: *mut c_int, options: c_int) -> pid_t {
     Sys::waitpid(pid, unsafe { Out::nullable(stat_loc) }, options).or_minus_one_errno()