net(docs): recv of 0 bytes with no error is a graceful close

2 files changed, 22 insertions, 5 deletions

diff --git a/core/net/errors.odin b/core/net/errors.odin
index 4853327b0..de53640fc 100644
--- a/core/net/errors.odin
+++ b/core/net/errors.odin
@@ -149,7 +149,8 @@ TCP_Recv_Error :: enum i32 {
 	Invalid_Argument,
 	// The socket is not connected.
 	Not_Connected,
-	// Connection was closed/broken/shutdown while receiving data.
+	// Connection was closed due to an error or shutdown.
+	// NOTE: a graceful close is indicated by a `0, nil` (0 bytes received and no error) return.
 	Connection_Closed,
 	// Timed out before being able to receive any data.
 	Timeout,
@@ -170,7 +171,8 @@ UDP_Recv_Error :: enum i32 {
 	Insufficient_Resources,
 	// Invalid socket or buffer given.
 	Invalid_Argument,
-	// "Connection" was refused by remote, or closed/broken/shutdown while receiving data.
+	// "Connection" was refused, or closed due to an error.
+	// NOTE: a graceful close is indicated by a `0, nil` (0 bytes received and no error) return.
 	Connection_Refused,
 	// Timed out before being able to receive any data.
 	Timeout,
@@ -193,7 +195,7 @@ TCP_Send_Error :: enum i32 {
 	Insufficient_Resources,
 	// Invalid socket or buffer given.
 	Invalid_Argument,
-	// Connection was closed/broken/shutdown while receiving data.
+	// Connection was closed/broken/shutdown while sending data.
 	Connection_Closed,
 	// The socket is not connected.
 	Not_Connected,
diff --git a/core/net/socket.odin b/core/net/socket.odin
index 7e96ba2b2..edb47cd0b 100644
--- a/core/net/socket.odin
+++ b/core/net/socket.odin
@@ -193,21 +193,36 @@ close :: proc(socket: Any_Socket) {
 	_close(socket)
 }
 
+/*
+	Receive data into a buffer from a TCP socket.
+
+	If no error occurs, `recv_tcp` returns the number of bytes received and `buf` will contain this data received.
+	If the connection has been gracefully closed, the return value is `0, nil` (0 bytes read and no error).
+*/
 recv_tcp :: proc(socket: TCP_Socket, buf: []byte) -> (bytes_read: int, err: TCP_Recv_Error) {
 	return _recv_tcp(socket, buf)
 }
 
+/*
+	Receive data into a buffer from a UDP socket.
+
+	If no error occurs, `recv_udp` returns the number of bytes received and `buf` will contain this data received.
+	If the "connection" has been gracefully closed, the return value is `0, nil` (0 bytes read and no error).
+*/
 recv_udp :: proc(socket: UDP_Socket, buf: []byte) -> (bytes_read: int, remote_endpoint: Endpoint, err: UDP_Recv_Error) {
 	return _recv_udp(socket, buf)
 }
 
 /*
-	Receive data from into a buffer from any socket.
+	Receive data into a buffer from any socket.
 
 	Note: `remote_endpoint` parameter is non-nil only if the socket type is UDP. On TCP sockets it
 	will always return `nil`.
 
-	Errors that can be returned: `TCP_Recv_Error`, or `UDP_Recv_Error`
+	Errors that can be returned: `TCP_Recv_Error`, or `UDP_Recv_Error`.
+
+	If no error occurs, `recv_any` returns the number of bytes received and `buf` will contain this data received.
+	If the connection has been gracefully closed, the return value is `0, nil, nil` (0 bytes read and no error).
 */
 recv_any :: proc(socket: Any_Socket, buf: []byte) -> (
 	bytes_read: int,