From 6aba744ed678cd875150b166910c3737555afd50 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Wed, 14 May 2025 01:32:45 -0400
Subject: [PATCH] include: Fill in some documentation gaps.
This should be most (or all?) of the missing docs.
Fixes #132.
---
include/SDL3_net/SDL_net.h | 120 ++++++++++++++++++++++++++++++++++---
1 file changed, 113 insertions(+), 7 deletions(-)
diff --git a/include/SDL3_net/SDL_net.h b/include/SDL3_net/SDL_net.h
index 662b85b..b43c0f7 100644
--- a/include/SDL3_net/SDL_net.h
+++ b/include/SDL3_net/SDL_net.h
@@ -41,20 +41,46 @@ extern "C" {
#endif
/**
- * Printable format: "%d.%d.%d", MAJOR, MINOR, MICRO
+ * The current major version of SDL_net headers.
+ *
+ * If this were SDL_net version 3.2.1, this value would be 3.
+ *
+ * \since This macro is available since SDL_net 3.0.0.
*/
#define SDL_NET_MAJOR_VERSION 3
+
+/**
+ * The current minor version of the SDL_net headers.
+ *
+ * If this were SDL_net version 3.2.1, this value would be 2.
+ *
+ * \since This macro is available since SDL_net 3.0.0.
+ */
#define SDL_NET_MINOR_VERSION 0
+
+/**
+ * The current micro (or patchlevel) version of the SDL_net headers.
+ *
+ * If this were SDL_net version 3.2.1, this value would be 1.
+ *
+ * \since This macro is available since SDL_net 3.0.0.
+ */
#define SDL_NET_MICRO_VERSION 0
/**
* This is the version number macro for the current SDL_net version.
+ *
+ * \since This macro is available since SDL_net 3.0.0.
+ *
+ * \sa NET_Version
*/
#define SDL_NET_VERSION \
SDL_VERSIONNUM(SDL_NET_MAJOR_VERSION, SDL_NET_MINOR_VERSION, SDL_NET_MICRO_VERSION)
/**
* This macro will evaluate to true if compiled with SDL_net at least X.Y.Z.
+ *
+ * \since This macro is available since SDL_net 3.0.0.
*/
#define SDL_NET_VERSION_ATLEAST(X, Y, Z) \
((SDL_NET_MAJOR_VERSION >= X) && \
@@ -118,7 +144,26 @@ extern SDL_DECLSPEC void SDLCALL NET_Quit(void);
/* hostname resolution API... */
-typedef struct NET_Address NET_Address; /**< Opaque struct that deals with computer-readable addresses. */
+/**
+ * Opaque representation of a computer-readable network address.
+ *
+ * This is an opaque datatype, to be treated by the app as a handle.
+ *
+ * SDL_net uses these to identify other servers; you use them to connect to a
+ * remote machine, and you use them to find out who connected to you. They are
+ * also used to decide what network interface to use when creating a server.
+ *
+ * These are intended to be protocol-independent; a given address might be for
+ * IPv4, IPv6, or something more esoteric. SDL_Net attempts to hide the
+ * differences.
+ *
+ * \since This datatype is available since SDL_Net 3.0.0.
+ *
+ * \sa NET_ResolveHostname
+ * \sa NET_GetLocalAddresses
+ * \sa NET_CompareAddresses
+ */
+typedef struct NET_Address NET_Address;
/**
* Resolve a human-readable hostname.
@@ -426,6 +471,23 @@ extern SDL_DECLSPEC void SDLCALL NET_FreeLocalAddresses(NET_Address **addresses)
/* Streaming (TCP) API... */
+/**
+ * An object that represents a streaming connection to another system.
+ *
+ * This is meant to be a reliable, stream-oriented connection, such as TCP.
+ *
+ * Each NET_StreamSocket represents a single connection between systems.
+ * Usually, a client app will have one connection to a server app on a
+ * different computer, and the server app might have many connections from
+ * different clients. Each of these connections communicate over a separate
+ * stream socket.
+ *
+ * \since This datatype is available since SDL_Net 3.0.0.
+ *
+ * \sa NET_CreateClient
+ * \sa NET_WriteToStreamSocket
+ * \sa NET_ReadFromStreamSocket
+ */
typedef struct NET_StreamSocket NET_StreamSocket; /**< a TCP socket. Reliable transmission, with the usual pros/cons. */
/**
@@ -526,6 +588,20 @@ extern SDL_DECLSPEC NET_StreamSocket * SDLCALL NET_CreateClient(NET_Address *add
*/
extern SDL_DECLSPEC int SDLCALL NET_WaitUntilConnected(NET_StreamSocket *sock, Sint32 timeout);
+/**
+ * The receiving end of a stream connection.
+ *
+ * This is an opaque datatype, to be treated by the app as a handle.
+ *
+ * Internally, this is what BSD sockets refers to as a "listen socket". Clients
+ * attempt to connect to a server, and if the server accepts the connection,
+ * will provide the app with a stream socket to send and receive data over that
+ * connection.
+ *
+ * \since This datatype is available since SDL_Net 3.0.0.
+ *
+ * \sa NET_CreateServer
+ */
typedef struct NET_Server NET_Server; /**< a listen socket, internally. Binds to a port, accepts connections. */
/**
@@ -938,14 +1014,45 @@ extern SDL_DECLSPEC void SDLCALL NET_DestroyStreamSocket(NET_StreamSocket *sock)
/* Datagram (UDP) API... */
+/**
+ * An object that represents a datagram connection to another system.
+ *
+ * This is meant to be an unreliable, packet-oriented connection, such as UDP.
+ *
+ * Datagram sockets follow different rules than stream sockets. They are not a
+ * reliable stream of bytes but rather packets, they are not limited to
+ * talking to a single other remote system, they do not maintain a single
+ * "connection" that can be dropped, and they are more nimble about network
+ * failures at the expense of being more complex to use. What makes sense for
+ * your app depends entirely on what your app is trying to accomplish.
+ *
+ * Generally the idea of a datagram socket is that you send data one chunk
+ * ("packet") at a time to any address you want, and it arrives whenever it
+ * gets there, even if later packets get there first, and maybe it doesn't get
+ * there at all, and you don't know when anything of this happens by default.
+ *
+ * \since This datatype is available since SDL_Net 3.0.0.
+ *
+ * \sa NET_CreateDatagramSocket
+ * \sa NET_SendDatagram
+ * \sa NET_ReceiveDatagram
+ */
typedef struct NET_DatagramSocket NET_DatagramSocket; /**< a UDP socket. Unreliable, packet-based transmission, with the usual pros/cons */
+/**
+ * The data provided for new incoming packets from NET_ReceiveDatagram().
+ *
+ * \since This datatype is available since SDL_Net 3.0.0.
+ *
+ * \sa NET_ReceiveDatagram
+ * \sa NET_DestroyDatagram
+ */
typedef struct NET_Datagram
{
NET_Address *addr; /**< this is unref'd by NET_DestroyDatagram. You only need to ref it if you want to keep it. */
- Uint16 port; /**< these do not have to come from the same port the receiver is bound to. */
- Uint8 *buf;
- int buflen;
+ Uint16 port; /**< these do not have to come from the same port the receiver is bound to. These are in host byte order, don't byteswap them! */
+ Uint8 *buf; /**< the payload of this datagram. */
+ int buflen; /**< the number of bytes available at `buf`. */
} NET_Datagram;
/**
@@ -1060,7 +1167,6 @@ extern SDL_DECLSPEC NET_DatagramSocket * SDLCALL NET_CreateDatagramSocket(NET_Ad
*/
extern SDL_DECLSPEC bool SDLCALL NET_SendDatagram(NET_DatagramSocket *sock, NET_Address *address, Uint16 port, const void *buf, int buflen);
-
/**
* Receive a new packet that a remote system sent to a datagram socket.
*
@@ -1070,7 +1176,7 @@ extern SDL_DECLSPEC bool SDLCALL NET_SendDatagram(NET_DatagramSocket *sock, NET_
* This call never blocks; if no new data isn't available at the time of the
* call, it returns true immediately. The caller can try again later.
*
- * On a successful call to this function, it returns zero, even if no new
+ * On a successful call to this function, it returns true, even if no new
* packets are available, so you should check for a successful return and a
* non-NULL value in `*dgram` to decide if a new packet is available.
*