From 5ec734a67269ff935d384627f16f831d7ca49cc2 Mon Sep 17 00:00:00 2001
From: Peter Limkilde Svendsen <peter.limkilde@gmail.com>
Date: Thu, 30 Jan 2025 21:19:20 +0100
Subject: [PATCH] Add docstrings and deprecations for arpa/inet.h

---
 src/header/arpa_inet/mod.rs | 47 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 46 insertions(+), 1 deletion(-)

diff --git a/src/header/arpa_inet/mod.rs b/src/header/arpa_inet/mod.rs
index 2af943a2fe..d59430db74 100644
--- a/src/header/arpa_inet/mod.rs
+++ b/src/header/arpa_inet/mod.rs
@@ -1,4 +1,6 @@
-//! arpa/inet implementation for Redox, following http://pubs.opengroup.org/onlinepubs/7908799/xns/arpainet.h.html
+//! `arpa/inet.h` implementation.
+//!
+//! See <https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/arpa_inet.h.html>.
 
 // TODO: set this for entire crate when possible
 #![deny(unsafe_op_in_unsafe_fn)]
@@ -18,32 +20,43 @@ use crate::{
     platform::{self, types::*},
 };
 
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/htonl.html>.
 #[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>.
 #[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>.
 #[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>.
 #[no_mangle]
 pub extern "C" fn ntohs(netshort: uint16_t) -> uint16_t {
     u16::from_be(netshort)
 }
 
+/// Non-POSIX, see <https://www.man7.org/linux/man-pages/man3/inet_aton.3.html>.
 #[no_mangle]
 pub unsafe extern "C" fn inet_aton(cp: *const c_char, inp: *mut in_addr) -> c_int {
     // TODO: octal/hex
     unsafe { inet_pton(AF_INET, cp, inp as *mut c_void) }
 }
 
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/inet_addr.html>.
+///
+/// # Deprecation
+/// The `inet_ntoa()` function was marked obsolescent in the Open Group Base
+/// Specifications Issue 8.
+#[deprecated]
 #[no_mangle]
 pub unsafe extern "C" fn inet_ntoa(addr: in_addr) -> *const c_char {
     static mut NTOA_ADDR: [c_char; 16] = [0; 16];
@@ -58,6 +71,7 @@ pub unsafe extern "C" fn inet_ntoa(addr: in_addr) -> *const c_char {
     }
 }
 
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/inet_ntop.html>.
 #[no_mangle]
 pub unsafe extern "C" fn inet_pton(domain: c_int, src: *const c_char, dest: *mut c_void) -> c_int {
     if domain != AF_INET {
@@ -87,6 +101,7 @@ pub unsafe extern "C" fn inet_pton(domain: c_int, src: *const c_char, dest: *mut
     }
 }
 
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/inet_ntop.html>.
 #[no_mangle]
 pub unsafe extern "C" fn inet_ntop(
     domain: c_int,
@@ -115,6 +130,12 @@ pub unsafe extern "C" fn inet_ntop(
     }
 }
 
+/// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/inet_addr.html>.
+///
+/// # Deprecated
+/// The `inet_addr()` function was marked obsolescent in the Open Group Base
+/// Specifications Issue 8.
+#[deprecated]
 #[no_mangle]
 pub unsafe extern "C" fn inet_addr(cp: *const c_char) -> in_addr_t {
     let mut val: in_addr = in_addr { s_addr: 0 };
@@ -126,6 +147,12 @@ pub unsafe extern "C" fn inet_addr(cp: *const c_char) -> in_addr_t {
     }
 }
 
+/// See <https://pubs.opengroup.org/onlinepubs/7908799/xns/inet_lnaof.html>.
+///
+/// # Deprecation
+/// The `inet_lnaof()` function was specified in Networking Services Issue 5,
+/// but not in the Open Group Base Specifications Issue 6 and later.
+#[deprecated]
 #[no_mangle]
 pub extern "C" fn inet_lnaof(input: in_addr) -> in_addr_t {
     if input.s_addr >> 24 < 128 {
@@ -137,6 +164,12 @@ pub extern "C" fn inet_lnaof(input: in_addr) -> in_addr_t {
     }
 }
 
+/// See <https://pubs.opengroup.org/onlinepubs/7908799/xns/inet_makeaddr.html>.
+///
+/// # Deprecation
+/// The `inet_makeaddr()` function was specified in Networking Services Issue
+/// 5, but not in the Open Group Base Specifications Issue 6 and later.
+#[deprecated]
 #[no_mangle]
 pub extern "C" fn inet_makeaddr(net: in_addr_t, host: in_addr_t) -> in_addr {
     let mut output: in_addr = in_addr { s_addr: 0 };
@@ -152,6 +185,12 @@ pub extern "C" fn inet_makeaddr(net: in_addr_t, host: in_addr_t) -> in_addr {
     output
 }
 
+/// See <https://pubs.opengroup.org/onlinepubs/7908799/xns/inet_netof.html>.
+///
+/// # Deprecation
+/// The `inet_netof()` function was specified in Networking Services Issue 5,
+/// but not in the Open Group Base Specifications Issue 6 and later.
+#[deprecated]
 #[no_mangle]
 pub extern "C" fn inet_netof(input: in_addr) -> in_addr_t {
     if input.s_addr >> 24 < 128 {
@@ -163,6 +202,12 @@ pub extern "C" fn inet_netof(input: in_addr) -> in_addr_t {
     }
 }
 
+/// See <https://pubs.opengroup.org/onlinepubs/7908799/xns/inet_network.html>.
+///
+/// # Deprecation
+/// The `inet_network()` function was specified in Networking Services Issue 5,
+/// but not in the Open Group Base Specifications Issue 6 and later.
+#[deprecated]
 #[no_mangle]
 pub unsafe extern "C" fn inet_network(cp: *mut c_char) -> in_addr_t {
     ntohl(unsafe { inet_addr(cp) })