cleanup the bits headers

src/header/bits_arpainet/cbindgen.toml

@@ -1,16 +1,17 @@
 # POSIX header spec: https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/arpa_inet.h.html
 #
-# The arpa/inet header should define the following functions:
+# arpa/inet.h should define the following functions:
 # - htonl
 # - htons
 # - ntohl
 # - ntohs
 #
-# They are also meant to be available in the netinet/in header.
-# The arpa/inet and netinet/in headers both say that they may include each other which creates a cycle.
-# To break the cycle we include netinet/in in the arpa/inet header and split out the above functions.
+# They are also meant to be available in netinet/in.h.
+# Both arpa/inet.h and netinet/in.h say that they may include each other which creates a cycle.
+# To break the cycle we include netinet/in.h in arpa/inet.h and split out the above functions.
 #
-# include inttypes.h to get uint16_t and uint32_t
+# inttypes.h brings in uint16_t and uint32_t
+# arpa/inet.h and netinet/in.h may include all of inttypes.h
 sys_includes = ["inttypes.h"]
 include_guard = "_RELIBC_BITS_ARPAINET_H"
 language = "C"

src/header/bits_arpainet/mod.rs

@@ -1,24 +1,32 @@
 use crate::platform::types::{uint16_t, uint32_t};
 
 /// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/htonl.html>.
+///
+/// Converts `hostlong` from host byte order to network byte order.
 #[unsafe(no_mangle)]
 pub extern "C" fn htonl(hostlong: uint32_t) -> uint32_t {
     hostlong.to_be()
 }
 
 /// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/htonl.html>.
+///
+/// Converts `hostshort` from host byte order to network byte order.
 #[unsafe(no_mangle)]
 pub extern "C" fn htons(hostshort: uint16_t) -> uint16_t {
     hostshort.to_be()
 }
 
 /// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/htonl.html>.
+///
+/// Converts `netlong` from network byte order to host byte order.
 #[unsafe(no_mangle)]
 pub extern "C" fn ntohl(netlong: uint32_t) -> uint32_t {
     u32::from_be(netlong)
 }
 
 /// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/htonl.html>.
+///
+/// Converts `netshort` from network byte order to host byte order.
 #[unsafe(no_mangle)]
 pub extern "C" fn ntohs(netshort: uint16_t) -> uint16_t {
     u16::from_be(netshort)

src/header/bits_clock-t/cbindgen.toml

@@ -6,10 +6,8 @@
 # - sys/times.h
 # - sys/types.h (where it should be defined)
 # - time.h
-sys_includes = []
 include_guard = "_RELIBC_BITS_CLOCK_T_H"
 language = "C"
-style = "type"
 no_includes = true
 cpp_compat = true
 [export]

src/header/bits_clock-t/mod.rs

@@ -1,5 +1,5 @@
 use crate::platform::types::c_long;
 
-/// Used for system times in clock ticks or CLOCKS_PER_SEC.
+/// Used for system times in clock ticks or `CLOCKS_PER_SEC`.
 #[allow(non_camel_case_types)]
 pub type clock_t = c_long;

src/header/bits_clockid-t/cbindgen.toml

@@ -5,10 +5,8 @@
 # POSIX headers that require clockid_t:
 # - sys/types.h (where it should be defined)
 # - time.h
-sys_includes = []
 include_guard = "_RELIBC_BITS_CLOCKID_T_H"
 language = "C"
-style = "type"
 no_includes = true
 cpp_compat = true
 [export]

src/header/bits_dev-t/cbindgen.toml

@@ -5,10 +5,8 @@
 # POSIX headers that require dev_t:
 # - sys/stat.h
 # - sys/types.h (where it should be defined)
-sys_includes = []
 include_guard = "_RELIBC_BITS_DEV_T_H"
 language = "C"
-style = "type"
 no_includes = true
 cpp_compat = true
 [export]

src/header/bits_gid-t/cbindgen.toml

@@ -5,14 +5,12 @@
 # POSIX headers that require gid_t:
 # - grp.h
 # - pwd.h
-# - sys/ipc.h (TODO not present in relibc)
+# - sys/ipc.h
 # - sys/stat.h
 # - sys/types.h (where it should be defined)
 # - unistd.h
-sys_includes = []
 include_guard = "_RELIBC_BITS_GID_T_H"
 language = "C"
-style = "type"
 no_includes = true
 cpp_compat = true
 [export]

src/header/bits_id-t/cbindgen.toml

@@ -6,10 +6,8 @@
 # - sys/resource.h
 # - sys/types.h (where it should be defined)
 # - sys/wait.h
-sys_includes = []
 include_guard = "_RELIBC_BITS_ID_T_H"
 language = "C"
-style = "type"
 no_includes = true
 cpp_compat = true
 [export]

src/header/bits_ino-t/cbindgen.toml

@@ -6,10 +6,8 @@
 # - dirent.h
 # - sys/stat.h
 # - sys/types.h (where it should be defined)
-sys_includes = []
 include_guard = "_RELIBC_BITS_INO_T_H"
 language = "C"
-style = "type"
 no_includes = true
 cpp_compat = true
 [export]

src/header/bits_iovec/cbindgen.toml

@@ -5,7 +5,6 @@
 # POSIX headers that require iovec:
 # - sys/socket.h
 # - sys/uio.h (where it should be defined)
-sys_includes = []
 after_includes = """
 #include <bits/size-t.h> // for size_t from sys/types.h
 """

src/header/bits_iovec/mod.rs

@@ -8,7 +8,9 @@ use crate::platform::types::{c_void, size_t};
 #[repr(C)]
 #[derive(Debug, CheckVsLibcCrate)]
 pub struct iovec {
+    /// Base address of a memory region for input or output.
     pub iov_base: *mut c_void,
+    /// The size of the memory pointed to by `iov_base`.
     pub iov_len: size_t,
 }
 

src/header/bits_key-t/cbindgen.toml

@@ -1,5 +1,7 @@
 # POSIX header spec: https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/sys_types.h.html
 #
+# This type is split out to prevent importing all of sys/types.h into other headers.
+#
 # POSIX headers that require key_t:
 # - sys/ipc.h
 # - sys/types (where it should be defined)

src/header/bits_key-t/mod.rs

@@ -1 +1,2 @@
+/// Used for XSI interprocess communication.
 pub type key_t = core::ffi::c_int;

src/header/bits_locale-t/cbindgen.toml

@@ -1,29 +1,23 @@
 # POSIX header spec: https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/locale.h.html
 #
-# The locale header should define this type but multiple headers make use of it.
-# This type is split out from the locale header to avoid including all of locale in the other headers.
+# This type is split out to prevent importing all of locale.h into other headers.
 #
 # POSIX headers that require locale_t:
 # - ctype.h
 # - langinfo.h
-# - libintl.h (Redox does not have this header, it seems to be supplied externally)
-# - monetary.h (TODO note exists, not currently imported)
+# - libintl.h (relibc does not define this header, supplied externally by gettext > libint)
+# - locale.h (where it should be defined)
+# - monetary.h
 # - string.h
-# - strings.h (TODO note exists, not currently imported)
-# - time.h (TODO note exists, not currently imported)
-# - wchar.h (required by *_l functions, no TODO note present)
-# - wctype.h (required by *_l functions, TODO note exists, not currently imported)
-sys_includes = []
+# - strings.h
+# - time.h
+# - wchar.h
+# - wctype.h
 include_guard = "_RELIBC_BITS_LOCALE_T_H"
 language = "C"
-style = "type"
 no_includes = true
 cpp_compat = true
-
 [export]
-include = [
-  "locale_t"
-]
-
+include = ["locale_t"]
 [enum]
 prefix_with_name = true

src/header/bits_locale-t/mod.rs

@@ -1 +1,2 @@
+/// Represents a locale object.
 pub type locale_t = *mut core::ffi::c_void;

src/header/bits_mode-t/cbindgen.toml

@@ -6,14 +6,12 @@
 # - fcntl.h
 # - ndbm.h (TODO not present in relibc)
 # - spawn.h (TODO not present in relibc)
-# - sys/ipc.h (TODO not present in relibc)
+# - sys/ipc.h
 # - sys/mman.h
 # - sys/stat.h
 # - sys/types.h (where it should be defined)
-sys_includes = []
 include_guard = "_RELIBC_BITS_MODE_T_H"
 language = "C"
-style = "type"
 no_includes = true
 cpp_compat = true
 [export]

src/header/bits_nlink-t/cbindgen.toml

@@ -5,10 +5,8 @@
 # POSIX headers that require nlink_t:
 # - sys/stat.h
 # - sys/types.h (where it should be defined)
-sys_includes = []
 include_guard = "_RELIBC_BITS_NLINK_T_H"
 language = "C"
-style = "type"
 no_includes = true
 cpp_compat = true
 [export]

src/header/bits_off-t/cbindgen.toml

@@ -9,10 +9,8 @@
 # - sys/stat.h
 # - sys/types.h (where it should be defined)
 # - unistd.h
-sys_includes = []
 include_guard = "_RELIBC_BITS_OFF_T_H"
 language = "C"
-style = "type"
 no_includes = true
 cpp_compat = true
 [export]

src/header/bits_pid-t/cbindgen.toml

@@ -8,17 +8,15 @@
 # - spawn.h (TODO not present in relibc)
 # - sys/msg.h (TODO not present in relibc)
 # - sys/sem.h (TODO not present in relibc)
-# - sys/shm.h (TODO not present in relibc)
+# - sys/shm.h
 # - sys/types.h (where it should be defined)
 # - sys/wait.h
 # - termios.h
 # - time.h
 # - unistd.h
 # - utmpx.h (TODO not present in relibc)
-sys_includes = []
 include_guard = "_RELIBC_BITS_PID_T_H"
 language = "C"
-style = "type"
 no_includes = true
 cpp_compat = true
 [export]

src/header/bits_pthread/cbindgen.toml

@@ -1,4 +1,14 @@
-sys_includes = []
+# POSIX header spec: https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/sys_types.h.html
+#
+# These types are split out to prevent importing all of sys/types.h into other headers.
+#
+# POSIX headers that require them:
+# - aio.h (pthread_attr_t only)
+# - pthread.h (all of them)
+# - signal (pthread_t and pthread_attr_t only)
+# - sys/types.h (where they should be defined)
+#
+# TODO split out pthread_t and pthread_attr_t
 include_guard = "_RELIBC_BITS_PTHREAD_H"
 language = "C"
 style = "type"

src/header/bits_reclen-t/cbindgen.toml

@@ -5,10 +5,8 @@
 # POSIX headers that require reclen_t:
 # - dirent.h
 # - sys/types.h (where it should be defined)
-sys_includes = []
 include_guard = "_RELIBC_BITS_RECLEN_T_H"
 language = "C"
-style = "type"
 no_includes = true
 cpp_compat = true
 [export]

src/header/bits_safamily-t/cbindgen.toml

@@ -1,21 +1,16 @@
 # POSIX header spec: https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/sys_socket.h.html
 #
-# The sys/socket header should define this type.
-# It is split out to avoid other headers from including all of sys/socket.
+# This type is split out to prevent importing all of sys/socket.h into other headers.
 #
 # POSIX headers that require sa_family_t:
 # - netinet/in.h
-# - sys/socket.h
+# - sys/socket.h (where it should be defined)
 # - sys/un.h
-sys_includes = []
 include_guard = "_RELIBC_BITS_SA_FAMILY_T_H"
 language = "C"
-style = "type"
 no_includes = true
 cpp_compat = true
-
 [export]
 include = ["sa_family_t"]
-
 [enum]
 prefix_with_name = true

src/header/bits_safamily-t/mod.rs

@@ -1,3 +1,4 @@
 use crate::platform::types::c_ushort;
 
+/// Represents a socket address family.
 pub type sa_family_t = c_ushort;

src/header/bits_sigset-t/cbindgen.toml

@@ -6,10 +6,8 @@
 # - poll.h
 # - signal.h (where it should be defined)
 # - sys/select.h
-sys_includes = []
 include_guard = "_RELIBC_BITS_SIGSET_T_H"
 language = "C"
-style = "type"
 no_includes = true
 cpp_compat = true
 [export]

src/header/bits_sigset-t/mod.rs

@@ -1,4 +1,5 @@
 use crate::platform::types::c_ulonglong;
 
+/// Integer type of an object used to represent sets of signals.
 #[allow(non_camel_case_types)]
 pub type sigset_t = c_ulonglong;

src/header/bits_size-t/cbindgen.toml

@@ -16,6 +16,7 @@
 # - regex.h
 # - search.h (TODO not present in relibc)
 # - signal.h
+# - stddef.h (where it should be defined)
 # - stdio.h
 # - stdlib.h
 # - string.h
@@ -23,19 +24,17 @@
 # - sys/mman.h
 # - sys/msg.h (TODO not present in relibc)
 # - sys/sem.h (TODO not present in relibc)
-# - sys/shm.h (TODO not present in relibc)
+# - sys/shm.h
 # - sys/socket.h
-# - sys/types.h (should be re-exported)
+# - sys/types.h (where it should be re-exported)
 # - sys/uio.h
 # - time.h
 # - uchar.h (TODO not present in relibc)
 # - unistd.h
 # - wchar.h
 # - wordexp.h (TODO not present in relibc)
-sys_includes = []
 include_guard = "_RELIBC_BITS_SIZE_T_H"
 language = "C"
-style = "type"
 no_includes = true
 cpp_compat = true
 [export]

src/header/bits_socklen-t/cbindgen.toml

@@ -1,6 +1,6 @@
 # POSIX header spec: https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/sys_socket.h.html
 #
-# This type is split out to prevent importing all of sys/socket.h to other headers.
+# This type is split out to prevent importing all of sys/socket.h into other headers.
 #
 # POSIX headers that require socklen_t:
 # - arpa/inet.h
@@ -12,7 +12,6 @@
 sys_includes = ["stdint.h"]
 include_guard = "_RELIBC_BITS_SOCKLEN_T_H"
 language = "C"
-style = "type"
 no_includes = true
 cpp_compat = true
 [export]

src/header/bits_socklen-t/mod.rs

@@ -1 +1,4 @@
+/// An integer type of at least 32bits width.
+///
+/// Used in various length representations relating to sockets.
 pub type socklen_t = u32;

src/header/bits_ssize-t/cbindgen.toml

@@ -13,10 +13,8 @@
 # - sys/types.h (where it should be defined)
 # - sys/uio.h
 # - unistd.h
-sys_includes = []
 include_guard = "_RELIBC_BITS_SSIZE_T_H"
 language = "C"
-style = "type"
 no_includes = true
 cpp_compat = true
 [export]

src/header/bits_suseconds-t/cbindgen.toml

@@ -6,10 +6,8 @@
 # - sys/select.h
 # - sys/time.h
 # - sys/types.h (where it should be defined)
-sys_includes = []
 include_guard = "_RELIBC_BITS_SUSECONDS_T_H"
 language = "C"
-style = "type"
 no_includes = true
 cpp_compat = true
 [export]

src/header/bits_sys_stat/cbindgen.toml

@@ -5,10 +5,8 @@
 # POSIX headers that require blkcnt_t and blksize_t:
 # - sys/stat.h
 # - sys/types.h (where they should be defined)
-sys_includes = []
 include_guard = "_RELIBC_BITS_SYS_STAT_H"
 language = "C"
-style = "type"
 no_includes = true
 cpp_compat = true
 [export]

src/header/bits_sys_statvfs/cbindgen.toml

@@ -5,10 +5,8 @@
 # POSIX headers that require fsblkcnt_t and fsfilcnt_t:
 # - sys/statvfs.h
 # - sys/types.h (where they should be defined)
-sys_includes = []
 include_guard = "_RELIBC_BITS_SYS_STATVFS_H"
 language = "C"
-style = "type"
 no_includes = true
 cpp_compat = true
 [export]

src/header/bits_time-t/cbindgen.toml

@@ -9,10 +9,8 @@
 # - sys/time.h
 # - sys/types.h (where it should be defined)
 # - time.h
-sys_includes = []
 include_guard = "_RELIBC_BITS_TIME_T_H"
 language = "C"
-style = "type"
 no_includes = true
 cpp_compat = true
 [export]

src/header/bits_timer-t/cbindgen.toml

@@ -5,10 +5,8 @@
 # POSIX headers that require timer_t:
 # - sys/types.h (where it should be defined)
 # - time.h
-sys_includes = []
 include_guard = "_RELIBC_BITS_TIMER_T_H"
 language = "C"
-style = "type"
 no_includes = true
 cpp_compat = true
 [export]

src/header/bits_timespec/cbindgen.toml

@@ -3,7 +3,7 @@
 # This type is split out to avoid including all of time.h in the other headers.
 #
 # POSIX headers that require timespec:
-# - aio.h (all functions currently unimplemented but timespec imported)
+# - aio.h
 # - poll.h
 # - sched.h
 # - semaphore.h
@@ -20,9 +20,7 @@ language = "C"
 style = "Tag"
 no_includes = true
 cpp_compat = true
-
-[enum]
-prefix_with_name = true
-
 [export]
 include = ["timespec"]
+[enum]
+prefix_with_name = true

src/header/bits_timespec/mod.rs

@@ -8,7 +8,9 @@ use crate::{
 #[repr(C)]
 #[derive(Clone, Default, Debug)]
 pub struct timespec {
+    /// Whole seconds.
     pub tv_sec: time_t,
+    /// Nanoseconds.
     pub tv_nsec: c_long,
 }
 

src/header/bits_timeval/cbindgen.toml

@@ -16,9 +16,7 @@ language = "C"
 style = "Tag"
 no_includes = true
 cpp_compat = true
-
-[enum]
-prefix_with_name = true
-
 [export]
 include = ["timeval"]
+[enum]
+prefix_with_name = true

src/header/bits_timeval/mod.rs

@@ -10,6 +10,8 @@ use crate::platform::types::{suseconds_t, time_t};
 #[allow(non_camel_case_types)]
 #[derive(Default)]
 pub struct timeval {
+    /// Seconds.
     pub tv_sec: time_t,
+    /// Microseconds.
     pub tv_usec: suseconds_t,
 }

src/header/bits_uid-t/cbindgen.toml

@@ -5,14 +5,12 @@
 # POSIX headers that require uid_t:
 # - pwd.h
 # - signal.h
-# - sys/ipc.h (TODO not present in relibc)
+# - sys/ipc.h
 # - sys/stat.h
 # - sys/types.h (where it should be defined)
 # - unistd.h
-sys_includes = []
 include_guard = "_RELIBC_BITS_UID_T_H"
 language = "C"
-style = "type"
 no_includes = true
 cpp_compat = true
 [export]

src/header/bits_useconds-t/cbindgen.toml

@@ -9,7 +9,6 @@
 sys_includes = ["features.h"]
 include_guard = "_RELIBC_BITS_USECONDS_T_H"
 language = "C"
-style = "type"
 no_includes = true
 cpp_compat = true
 [export]

src/header/bits_winsize/mod.rs

@@ -3,13 +3,22 @@ use crate::platform::types::c_ushort;
 #[repr(C)]
 #[derive(Default)]
 pub struct winsize {
+    /// Rows, in characters.
     ws_row: c_ushort,
+    /// Columns, in characters.
     ws_col: c_ushort,
+    /// Non-POSIX, see <https://www.man7.org/linux/man-pages/man2/TIOCSWINSZ.2const.html>.
+    ///
+    /// Unused.
     ws_xpixel: c_ushort,
+    /// Non-POSIX, see <https://www.man7.org/linux/man-pages/man2/TIOCSWINSZ.2const.html>.
+    ///
+    /// Unused.
     ws_ypixel: c_ushort,
 }
 
 impl winsize {
+    /// Return the row and column in that order in a tuple.
     pub fn get_row_col(&self) -> (c_ushort, c_ushort) {
         (self.ws_row, self.ws_col)
     }