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)