[net] Assorted cleanup

- Remove some old comments

- Fix some doc comments

- Improve some doc comments

- Unify name of the errors related to UDP packet sizes
   (i.e: recv buffer too small, and message too big to send)

4 files changed, 18 insertions, 31 deletions

diff --git a/core/net/addr.odin b/core/net/addr.odin
index be04be15e..f0c47e926 100644
--- a/core/net/addr.odin
+++ b/core/net/addr.odin
@@ -587,7 +587,7 @@ address_to_string :: proc(addr: Address, allocator := context.temp_allocator) ->
 }
 
 // Returns a temporarily-allocated string representation of the endpoint.
-// If there's a port, uses the `[address]:port` format.
+// If there's a port, uses the `ip4address:port` or `[ip6address]:port` format, respectively.
 endpoint_to_string :: proc(ep: Endpoint, allocator := context.temp_allocator) -> string {
 	if ep.port == 0 {
 		return address_to_string(ep.address, allocator)
diff --git a/core/net/errors_darwin.odin b/core/net/errors_darwin.odin
index 39cf4c665..c80d2cf56 100644
--- a/core/net/errors_darwin.odin
+++ b/core/net/errors_darwin.odin
@@ -109,12 +109,12 @@ TCP_Recv_Error :: enum c.int {
 }
 
 UDP_Recv_Error :: enum c.int {
-	None           = 0,
-	Truncated      = c.int(os.EMSGSIZE), // The buffer is too small to fit the entire message, and the message was truncated.
-	Not_Socket     = c.int(os.ENOTSOCK), // The so-called socket is not an open socket.
-	Not_Descriptor = c.int(os.EBADF),    // The so-called socket is, in fact, not even a valid descriptor.
-	Bad_Buffer     = c.int(os.EFAULT),   // The buffer did not point to a valid location in memory.
-	Interrupted    = c.int(os.EINTR),    // A signal occurred before any data was transmitted. See signal(7).
+	None             = 0,
+	Buffer_Too_Small = c.int(os.EMSGSIZE), // The buffer is too small to fit the entire message, and the message was truncated. When this happens, the rest of message is lost.
+	Not_Socket       = c.int(os.ENOTSOCK), // The so-called socket is not an open socket.
+	Not_Descriptor   = c.int(os.EBADF),    // The so-called socket is, in fact, not even a valid descriptor.
+	Bad_Buffer       = c.int(os.EFAULT),   // The buffer did not point to a valid location in memory.
+	Interrupted      = c.int(os.EINTR),    // A signal occurred before any data was transmitted. See signal(7).
 
 	// The send timeout duration passed before all data was sent. See Socket_Option.Send_Timeout.
 	// NOTE: No, really. Presumably this means something different for nonblocking sockets...
@@ -122,11 +122,9 @@ UDP_Recv_Error :: enum c.int {
 	Socket_Not_Bound = c.int(os.EINVAL), // The socket must be bound for this operation, but isn't.
 }
 
-// TODO
 TCP_Send_Error :: enum c.int {
 	None                      = 0,
 
-	// TODO: merge with other errors?
 	Aborted                   = c.int(os.ECONNABORTED), 
 	Connection_Closed         = c.int(os.ECONNRESET),
 	Not_Connected             = c.int(os.ENOTCONN),
@@ -151,7 +149,7 @@ TCP_Send_Error :: enum c.int {
 // TODO
 UDP_Send_Error :: enum c.int {
 	None                        = 0,
-	Truncated                   = c.int(os.EMSGSIZE), // The message is too big. No data was sent.
+	Message_Too_Long            = c.int(os.EMSGSIZE), // The message is larger than the maximum UDP packet size. No data was sent.
 
 	// TODO: not sure what the exact circumstances for this is yet
 	Network_Unreachable         = c.int(os.ENETUNREACH),
diff --git a/core/net/errors_linux.odin b/core/net/errors_linux.odin
index 9366f4435..d76132ad5 100644
--- a/core/net/errors_linux.odin
+++ b/core/net/errors_linux.odin
@@ -105,9 +105,7 @@ TCP_Recv_Error :: enum c.int {
 UDP_Recv_Error :: enum c.int {
 	None             = 0,
 
-	// The buffer is too small to fit the entire message, and the message was truncated.
-	// When this happens, the rest of message is lost.
-	Buffer_Too_Small = c.int(os.EMSGSIZE), 
+	Buffer_Too_Small = c.int(os.EMSGSIZE), // The buffer is too small to fit the entire message, and the message was truncated. When this happens, the rest of message is lost.
 	Not_Socket       = c.int(os.ENOTSOCK), // The so-called socket is not an open socket.
 	Not_Descriptor   = c.int(os.EBADF),    // The so-called socket is, in fact, not even a valid descriptor.
 	Bad_Buffer       = c.int(os.EFAULT),   // The buffer did not point to a valid location in memory.
@@ -119,10 +117,8 @@ UDP_Recv_Error :: enum c.int {
 	Socket_Not_Bound = c.int(os.EINVAL), // The socket must be bound for this operation, but isn't.
 }
 
-// TODO
 TCP_Send_Error :: enum c.int {
 	None                      = 0,
-	// TODO(tetra): merge with other errors?
 	Aborted                   = c.int(os.ECONNABORTED), 
 	Connection_Closed         = c.int(os.ECONNRESET),
 	Not_Connected             = c.int(os.ENOTCONN),
@@ -135,16 +131,16 @@ TCP_Send_Error :: enum c.int {
 	// doesn't fit in the send queue.
 	No_Buffer_Space_Available = c.int(os.ENOBUFS),
 	Offline                   = c.int(os.ENETDOWN),
-	Host_Unreachable          = c.int(os.EHOSTUNREACH), // A signal occurred before any data was transmitted. See signal(7).
-	Interrupted               = c.int(os.EINTR),        // The send timeout duration passed before all data was sent. See Socket_Option.Send_Timeout.
-	Timeout                   = c.int(os.EWOULDBLOCK),  // NOTE: No, really. Presumably this means something different for nonblocking sockets...
+	Host_Unreachable          = c.int(os.EHOSTUNREACH),
+	Interrupted               = c.int(os.EINTR),        // A signal occurred before any data was transmitted. See signal(7).
+	Timeout                   = c.int(os.EWOULDBLOCK),  // The send timeout duration passed before all data was sent. See Socket_Option.Send_Timeout.
 	Not_Socket                = c.int(os.ENOTSOCK),     // The so-called socket is not an open socket.
 }
 
 // TODO
 UDP_Send_Error :: enum c.int {
 	None                        = 0,
-	Message_Too_Long            = c.int(os.EMSGSIZE),    // The message is too big. No data was sent.
+	Message_Too_Long            = c.int(os.EMSGSIZE), // The message is larger than the maximum UDP packet size. No data was sent.
 
 	// TODO: not sure what the exact circumstances for this is yet
 	Network_Unreachable         = c.int(os.ENETUNREACH), 
diff --git a/core/net/errors_windows.odin b/core/net/errors_windows.odin
index 272aa0a96..0538c2b82 100644
--- a/core/net/errors_windows.odin
+++ b/core/net/errors_windows.odin
@@ -92,8 +92,6 @@ TCP_Recv_Error :: enum c.int {
 	Not_Socket                = win.WSAENOTSOCK,
 	Shutdown                  = win.WSAESHUTDOWN,
 	Would_Block               = win.WSAEWOULDBLOCK,
-
-	// TODO: not functionally different from Reset; merge?
 	Aborted                   = win.WSAECONNABORTED, 
 	Timeout                   = win.WSAETIMEDOUT,
 
@@ -107,11 +105,8 @@ TCP_Recv_Error :: enum c.int {
 UDP_Recv_Error :: enum c.int {
 	None                      = 0,
 	Network_Subsystem_Failure = win.WSAENETDOWN,
-
-	// TODO: not functionally different from Reset; merge?
-	// UDP packets are limited in size, and the length of the incoming message exceeded it.
-	Aborted                   = win.WSAECONNABORTED, 
-	Truncated                 = win.WSAEMSGSIZE,
+	Aborted                   = win.WSAECONNABORTED,
+	Buffer_Too_Small          = win.WSAEMSGSIZE,     // The buffer is too small to fit the entire message, and the message was truncated. When this happens, the rest of message is lost.
 	Remote_Not_Listening      = win.WSAECONNRESET,   // The machine at the remote endpoint doesn't have the given port open to receiving UDP data.
 	Shutdown                  = win.WSAESHUTDOWN,
 	Broadcast_Disabled        = win.WSAEACCES,       // A broadcast address was specified, but the .Broadcast socket option isn't set.
@@ -133,7 +128,6 @@ UDP_Recv_Error :: enum c.int {
 TCP_Send_Error :: enum c.int {
 	None                      = 0,
 	
-	// TODO: not functionally different from Reset; merge?
 	Aborted                   = win.WSAECONNABORTED, 
 	Not_Connected             = win.WSAENOTCONN,
 	Shutdown                  = win.WSAESHUTDOWN,
@@ -159,10 +153,9 @@ UDP_Send_Error :: enum c.int {
 	None                      = 0,
 	Network_Subsystem_Failure = win.WSAENETDOWN,
 
-	// TODO: not functionally different from Reset; merge?
-	Aborted                   = win.WSAECONNABORTED, // UDP packets are limited in size, and len(buf) exceeded it.
-	Message_Too_Long          = win.WSAEMSGSIZE,     // The machine at the remote endpoint doesn't have the given port open to receiving UDP data.
-	Remote_Not_Listening      = win.WSAECONNRESET,
+	Aborted                   = win.WSAECONNABORTED,
+	Message_Too_Long          = win.WSAEMSGSIZE, 	 // The message is larger than the maximum UDP packet size.
+	Remote_Not_Listening      = win.WSAECONNRESET,   // The machine at the remote endpoint doesn't have the given port open to receiving UDP data.
 	Shutdown                  = win.WSAESHUTDOWN,    // A broadcast address was specified, but the .Broadcast socket option isn't set.
 	Broadcast_Disabled        = win.WSAEACCES,
 	Bad_Buffer                = win.WSAEFAULT,       // Connection is broken due to keepalive activity detecting a failure during the operation.