From 285d08bb3b74a0f6037d94cc57f6a28382cb8c06 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Fri, 17 Jun 2022 14:51:35 -0400
Subject: [PATCH] Let wikiheaders.pl re-wordwrap the comments.
---
SDL_net.h | 334 +++++++++++++++++++++++++++---------------------------
1 file changed, 165 insertions(+), 169 deletions(-)
diff --git a/SDL_net.h b/SDL_net.h
index e63c49d..e657682 100644
--- a/SDL_net.h
+++ b/SDL_net.h
@@ -106,17 +106,17 @@ extern DECLSPEC const SDLNet_version * SDLCALL SDLNet_Linked_Version(void);
/**
* Initialize SDL_net.
*
- * You must successfully call this function before it is safe to
- * call any other function in this library, with one exception:
- * A human-readable error message can be retrieved from
- * SDLNet_GetError() when if this function fails.
+ * You must successfully call this function before it is safe to call any
+ * other function in this library, with one exception: A human-readable error
+ * message can be retrieved from SDLNet_GetError() when if this function
+ * fails.
*
- * SDL must be initialized before calls to functions in this library,
- * because this library uses utility functions from the SDL library.
+ * SDL must be initialized before calls to functions in this library, because
+ * this library uses utility functions from the SDL library.
*
- * It is safe to call this more than once; the library keeps a
- * counter of init calls, and decrements it on each call to SDLNet_Quit,
- * so you must pair your init and quit calls.
+ * It is safe to call this more than once; the library keeps a counter of init
+ * calls, and decrements it on each call to SDLNet_Quit, so you must pair your
+ * init and quit calls.
*
* \returns 0 on success, -1 on error.
*/
@@ -125,9 +125,9 @@ extern DECLSPEC int SDLCALL SDLNet_Init(void);
/**
* Deinitialize SDL_net.
*
- * You must call this when done with the library, to free internal
- * resources. It is safe to call this when the library isn't initialized,
- * as it will just return immediately.
+ * You must call this when done with the library, to free internal resources.
+ * It is safe to call this when the library isn't initialized, as it will just
+ * return immediately.
*
* Once you have as many quit calls as you have had successful calls to
* SDLNet_Init, the library will actually deinitialize.
@@ -160,8 +160,8 @@ typedef struct {
*
* If `host` is NULL, the resolved host will be set to `INADDR_ANY`.
*
- * If the host couldn't be resolved, the host portion of the returned
- * address will be INADDR_NONE, and the function will return -1.
+ * If the host couldn't be resolved, the host portion of the returned address
+ * will be INADDR_NONE, and the function will return -1.
*
* \param address to be filled in with the resolved address and port.
* \param host the hostname to lookup (like "libsdl.org")
@@ -173,11 +173,10 @@ extern DECLSPEC int SDLCALL SDLNet_ResolveHost(IPaddress *address, const char *h
/**
* Resolve an IP address to a host name in canonical form.
*
- * If the IP couldn't be resolved, this function returns NULL,
- * otherwise a pointer to a static buffer containing the hostname
- * is returned.
+ * If the IP couldn't be resolved, this function returns NULL, otherwise a
+ * pointer to a static buffer containing the hostname is returned.
*
- * \warning Note that this function is not thread-safe!
+ * **Warning**: Note that this function is not thread-safe!
*
* \param ip the IP address to resolve into a hostname.
*/
@@ -201,10 +200,10 @@ typedef struct _TCPsocket *TCPsocket;
* Open a TCP network socket.
*
* If `ip->host` is INADDR_NONE or INADDR_ANY, this creates a local server
- * socket on the given port, otherwise a TCP connection to the remote
- * host and port is attempted. The address passed in should already be
- * swapped to network byte order (addresses returned from
- * SDLNet_ResolveHost() are already in the correct form).
+ * socket on the given port, otherwise a TCP connection to the remote host and
+ * port is attempted. The address passed in should already be swapped to
+ * network byte order (addresses returned from SDLNet_ResolveHost() are
+ * already in the correct form).
*
* \param ip The address to open a connection to (or to host a server on).
* \returns the newly created socket, or NULL if there was an error.
@@ -216,9 +215,9 @@ extern DECLSPEC TCPsocket SDLCALL SDLNet_TCP_Open(IPaddress *ip);
/**
* Accept an incoming connection on the given server socket.
*
- * `server` must be a socket returned by SDLNet_TCP_Open with an address
- * of INADDR_NONE or INADDR_ANY (a "server socket"). Other sockets do not
- * accept connections.
+ * `server` must be a socket returned by SDLNet_TCP_Open with an address of
+ * INADDR_NONE or INADDR_ANY (a "server socket"). Other sockets do not accept
+ * connections.
*
* \param server the server socket to accept a connection on.
* \returns the newly created socket, or NULL if there was an error.
@@ -230,9 +229,9 @@ extern DECLSPEC TCPsocket SDLCALL SDLNet_TCP_Accept(TCPsocket server);
*
* If the socket is a server socket, this function returns NULL.
*
- * This returns a pointer to internal memory; you should not modify or
- * free it, and should assume it's only valid until the socket is given
- * to SDLNet_TCP_Close.
+ * This returns a pointer to internal memory; you should not modify or free
+ * it, and should assume it's only valid until the socket is given to
+ * SDLNet_TCP_Close.
*
* \param sock the socket to query.
* \returns the address information for the socket.
@@ -242,24 +241,24 @@ extern DECLSPEC IPaddress * SDLCALL SDLNet_TCP_GetPeerAddress(TCPsocket sock);
/**
* Send data over a non-server socket.
*
- * `sock` must be a valid socket that was created by SDLNet_TCP_Open with
- * a specific address, or SDLNet_TCP_Accept.
+ * `sock` must be a valid socket that was created by SDLNet_TCP_Open with a
+ * specific address, or SDLNet_TCP_Accept.
*
* This function sends `len` bytes, pointed to by `data` over the non-server
* socket `sock`.
*
- * This function returns the actual amount of data sent. If the return value
+ * This function returns the actual amount of data sent. If the return value
* is less than the amount of data sent, then either the remote connection was
* closed, or an unknown socket error occurred.
*
- * \warning This function may block!
+ * This function may block!
*
* \param sock the socket to send data to.
* \param data a pointer to the bytes to send.
* \param len the number of bytes, pointed to by `data`, to transmit.
* \returns number of bytes sent, which might be less if there was a problem
- * or connection failure. If the socket is invalid, this function
- * can return -1, but in valid uses it'll return >= 0.
+ * or connection failure. If the socket is invalid, this function can
+ * return -1, but in valid uses it'll return >= 0.
*
* \sa SDLNet_TCP_Recv
*/
@@ -269,22 +268,21 @@ extern DECLSPEC int SDLCALL SDLNet_TCP_Send(TCPsocket sock, const void *data,
/**
* Receive data from a non-server socket.
*
- * `sock` must be a valid socket that was created by SDLNet_TCP_Open with
- * a specific address, or SDLNet_TCP_Accept.
+ * `sock` must be a valid socket that was created by SDLNet_TCP_Open with a
+ * specific address, or SDLNet_TCP_Accept.
*
- * Receive up to `maxlen` bytes of data over the non-server socket `sock`,
- * and store them in the buffer pointed to by `data`.
+ * Receive up to `maxlen` bytes of data over the non-server socket `sock`, and
+ * store them in the buffer pointed to by `data`.
*
- * This function returns the actual amount of data received. If the return
+ * This function returns the actual amount of data received. If the return
* value is less than or equal to zero, then either the remote connection was
* closed, or an unknown socket error occurred.
*
* Note that this will return the number of bytes available at the first
* moment the socket is able to see new data. If packets are coming in slowly
- * from the network, this might be less data than you expect at a given
- * time.
+ * from the network, this might be less data than you expect at a given time.
*
- * \warning This function may block!
+ * This function may block!
*
* \param sock the socket to send data to.
* \param data a pointer to where to store received data.
@@ -299,8 +297,8 @@ extern DECLSPEC int SDLCALL SDLNet_TCP_Recv(TCPsocket sock, void *data, int maxl
* Close a TCP network socket
*
* All TCP sockets (server and non-server) are deinitialized through this
- * function. Call this once you are done with a socket, and assume the
- * handle is invalid once you have.
+ * function. Call this once you are done with a socket, and assume the handle
+ * is invalid once you have.
*
* Closing a socket will disconnect any communication and free its resources.
*
@@ -331,13 +329,14 @@ typedef struct {
*
* This allocates a packet with `size` bytes of space for payload.
*
- * When done with this packet, you can free it with SDLNet_FreePacket.
- * Packets can be used multiple times; you don't have to allocate a new
- * one for each piece of data you intend to send.
+ * When done with this packet, you can free it with SDLNet_FreePacket. Packets
+ * can be used multiple times; you don't have to allocate a new one for each
+ * piece of data you intend to send.
*
* You can allocate multiple packets at once with SDLNet_AllocPacketV.
*
- * \param size the maximum number of bytes of payload this packet will contain.
+ * \param size the maximum number of bytes of payload this packet will
+ * contain.
* \returns the new packet, or NULL if the function ran out of memory.
*
* \sa SDLNet_ResizePacket
@@ -350,25 +349,25 @@ extern DECLSPEC UDPpacket * SDLCALL SDLNet_AllocPacket(int size);
/**
* Reallocate a UDP packet's payload space.
*
- * This takes an existing packet and makes sure it can contain at
- * least `newsize` bytes of space for payload.
+ * This takes an existing packet and makes sure it can contain at least
+ * `newsize` bytes of space for payload.
*
- * When done with this packet, you can free it with SDLNet_FreePacket.
- * Packets can be used multiple times; you don't have to allocate a new
- * one for each piece of data you intend to send.
+ * When done with this packet, you can free it with SDLNet_FreePacket. Packets
+ * can be used multiple times; you don't have to allocate a new one for each
+ * piece of data you intend to send.
*
- * Please note that on memory allocation failure, this function will leave
- * the existing buffer alone, and _will return the original buffer size_.
- * It will not return an error value, it'll just leave the packet as it was!
+ * Please note that on memory allocation failure, this function will leave the
+ * existing buffer alone, and _will return the original buffer size_. It will
+ * not return an error value, it'll just leave the packet as it was!
*
- * \warning Existing contents of the packet's data are lost when resizing,
- * whether you are growing or shrinking the payload space, since
- * SDL_net does not realloc the existing data.
+ * **Warning**: Existing contents of the packet's data are lost when resizing,
+ * whether you are growing or shrinking the payload space, since SDL_net does
+ * not realloc the existing data.
*
- * \param newsize the new maximum number of bytes of payload this packet
- * will contain.
- * \returns the new maximum payload size, which will be unchanged from
- * the previous if the system ran out of memory.
+ * \param newsize the new maximum number of bytes of payload this packet will
+ * contain.
+ * \returns the new maximum payload size, which will be unchanged from the
+ * previous if the system ran out of memory.
*
* \sa SDLNet_AllocPacket
* \sa SDLNet_FreePacket
@@ -379,9 +378,8 @@ extern DECLSPEC int SDLCALL SDLNet_ResizePacket(UDPpacket *packet, int newsize);
/**
* Dispose of a UDP packet.
*
- * This frees both the packet's payload and the packet itself. Once this
- * call completes, the packet's pointer is invalid and should not be used
- * anymore.
+ * This frees both the packet's payload and the packet itself. Once this call
+ * completes, the packet's pointer is invalid and should not be used anymore.
*
* \param packet the packet to free.
*
@@ -395,9 +393,8 @@ extern DECLSPEC void SDLCALL SDLNet_FreePacket(UDPpacket *packet);
*
* This allocates `howmany` packets at once,each `size` bytes long.
*
- * You must free the results of this function with SDLNet_FreePacketV,
- * and must not free individual packets from this function with
- * SDLNet_FreePacket.
+ * You must free the results of this function with SDLNet_FreePacketV, and
+ * must not free individual packets from this function with SDLNet_FreePacket.
*
* \param howmany the number of packets to allocate.
* \param size the maximum bytes of payload each packet should contain.
@@ -412,13 +409,13 @@ extern DECLSPEC UDPpacket ** SDLCALL SDLNet_AllocPacketV(int howmany, int size);
/**
* Free a UDP packet vector (array of packets).
*
- * This frees the results of a previous call to SDLNet_AllocPacketV(),
- * freeing both the set of packets and the array that holds them.
+ * This frees the results of a previous call to SDLNet_AllocPacketV(), freeing
+ * both the set of packets and the array that holds them.
*
* It is safe to free a NULL array through here; it's a harmless no-op.
*
- * You must not use this to free packets allocated through any function
- * other than SDLNet_AllocPacketV().
+ * You must not use this to free packets allocated through any function other
+ * than SDLNet_AllocPacketV().
*
* \param packetV the results of a call to SDLNet_AllocPacketV().
*
@@ -431,16 +428,16 @@ extern DECLSPEC void SDLCALL SDLNet_FreePacketV(UDPpacket **packetV);
*
* If `port` is non-zero, the UDP socket is bound to a local port.
*
- * The `port` should be given in native byte order, but is used
- * internally in network (big endian) byte order, in addresses, etc.
- * This allows other systems to send to this socket via a known port.
+ * The `port` should be given in native byte order, but is used internally in
+ * network (big endian) byte order, in addresses, etc. This allows other
+ * systems to send to this socket via a known port.
*
- * Note that UDP sockets at the platform layer "bind" to a nework port
- * number, but SDL_net's UDP sockets also "bind" to a "channel" on top of
- * that, with SDLNet_UDP_Bind(). But the term is used for both.
+ * Note that UDP sockets at the platform layer "bind" to a nework port number,
+ * but SDL_net's UDP sockets also "bind" to a "channel" on top of that, with
+ * SDLNet_UDP_Bind(). But the term is used for both.
*
- * When you are done communicating over the returned socket, you can
- * shut it down and free its resources with SDLNet_UDP_Close().
+ * When you are done communicating over the returned socket, you can shut it
+ * down and free its resources with SDLNet_UDP_Close().
*
* \param port the UDP port to bind this socket to.
* \returns a new UDP socket, ready to communicate.
@@ -456,8 +453,8 @@ extern DECLSPEC UDPsocket SDLCALL SDLNet_UDP_Open(Uint16 port);
* SDL_net can optionally, at random, drop packets that are being sent and
* received, to simulate bad networking conditions. As these sort of
* conditions can happen in the real world but likely won't between machines
- * on the same LAN, you can use this function in testing to make sure your
- * app is robust against network problems even on a fast, reliable network.
+ * on the same LAN, you can use this function in testing to make sure your app
+ * is robust against network problems even on a fast, reliable network.
*
* You probably don't want to use this function outside of local testing.
*
@@ -470,21 +467,22 @@ extern DECLSPEC void SDLCALL SDLNet_UDP_SetPacketLoss(UDPsocket sock, int percen
/**
* Bind an address to the requested channel on the UDP socket.
*
- * Note that UDP sockets at the platform layer "bind" to a nework port
- * number, but SDL_net's UDP sockets also "bind" to a "channel" on top of
- * that, with SDLNet_UDP_Bind(). But the term is used for both.
+ * Note that UDP sockets at the platform layer "bind" to a nework port number,
+ * but SDL_net's UDP sockets also "bind" to a "channel" on top of that, with
+ * SDLNet_UDP_Bind(). But the term is used for both.
*
- * If `channel` is -1, then the first unbound channel that has not yet
- * been bound to the maximum number of addresses will be bound with
- * the given address as it's primary address.
+ * If `channel` is -1, then the first unbound channel that has not yet been
+ * bound to the maximum number of addresses will be bound with the given
+ * address as it's primary address.
*
- * If the channel is already bound, this new address will be added to the
- * list of valid source addresses for packets arriving on the channel.
- * If the channel is not already bound, then the address becomes the primary
- * address, to which all outbound packets on the channel are sent.
+ * If the channel is already bound, this new address will be added to the list
+ * of valid source addresses for packets arriving on the channel. If the
+ * channel is not already bound, then the address becomes the primary address,
+ * to which all outbound packets on the channel are sent.
*
* \param sock the UDP socket to bind an address to a channel on.
- * \param channel the channel of the socket to bind to, or -1 to use the first available channel.
+ * \param channel the channel of the socket to bind to, or -1 to use the first
+ * available channel.
* \param address the address to bind to the socket's channel.
* \returns the channel which was bound, or -1 on error.
*
@@ -495,9 +493,9 @@ extern DECLSPEC int SDLCALL SDLNet_UDP_Bind(UDPsocket sock, int channel, const I
/**
* Unbind all addresses from the given channel.
*
- * Note that UDP sockets at the platform layer "bind" to a nework port
- * number, but SDL_net's UDP sockets also "bind" to a "channel" on top of
- * that, with SDLNet_UDP_Bind(). But the term is used for both.
+ * Note that UDP sockets at the platform layer "bind" to a nework port number,
+ * but SDL_net's UDP sockets also "bind" to a "channel" on top of that, with
+ * SDLNet_UDP_Bind(). But the term is used for both.
*
* \param sock the UDP socket to unbind addresses from a channel on.
* \param channel the channel of the socket to unbind.
@@ -509,8 +507,8 @@ extern DECLSPEC void SDLCALL SDLNet_UDP_Unbind(UDPsocket sock, int channel);
/**
* Get the IP address of the remote system for a socket and channel.
*
- * If `channel` is -1, then the primary IP port of the UDP socket is
- * returned -- this is only meaningful for sockets opened with a specific port.
+ * If `channel` is -1, then the primary IP port of the UDP socket is returned
+ * -- this is only meaningful for sockets opened with a specific port.
*
* If the channel is not bound and not -1, this function returns NULL.
*
@@ -526,28 +524,28 @@ extern DECLSPEC IPaddress * SDLCALL SDLNet_UDP_GetPeerAddress(UDPsocket sock, in
* If the channel specified in the packet is -1, the packet will be sent to
* the address in the `src` member of the packet.
*
- * Each packet will be updated with the status of the packet after it has
- * been sent, -1 if the packet send failed.
+ * Each packet will be updated with the status of the packet after it has been
+ * sent, -1 if the packet send failed.
*
* This function takes an array of packets but does not need to be allocated
* through SDLNet_AllocPacketV; if you supply your own array of packets you
* allocated individually, that is okay.
*
- * \warning UDP is an _unreliable protocol_, which means we can report
+ * **Warning**: UDP is an _unreliable protocol_, which means we can report
* that your packet has been successfully sent from your machine, but then it
* never makes it to its destination when a router along the way quietly drops
* it. If this happens--and this is a common result on the internet!--you will
* not know the packet never made it. Also, packets may arrive in a different
* order than you sent them. Plan accordingly!
*
- * \warning The maximum size of the packet is limited by the MTU (Maximum
- * Transfer Unit) of the transport medium. It can be as low as 250 bytes for
- * some PPP links, and as high as 1500 bytes for ethernet. Different sizes
- * can be sent, but the system might split it into multiple transmission
- * fragments behind the scenes, that need to be reassembled on the other side
- * (and the packet is lost if any fragment is lost in transit).
- * So the less you can reasonably send in a single packet, the better, as it
- * will be more reliable and lower latency.
+ * **Warning**: The maximum size of the packet is limited by the MTU (Maximum
+ * Transfer Unit) of the transport medium. It can be as low as 250 bytes for
+ * some PPP links, and as high as 1500 bytes for ethernet. Different sizes can
+ * be sent, but the system might split it into multiple transmission fragments
+ * behind the scenes, that need to be reassembled on the other side (and the
+ * packet is lost if any fragment is lost in transit). So the less you can
+ * reasonably send in a single packet, the better, as it will be more reliable
+ * and lower latency.
*
* \returns the number of packets successfully sent from this machine.
*
@@ -561,24 +559,24 @@ extern DECLSPEC int SDLCALL SDLNet_UDP_SendV(UDPsocket sock, UDPpacket **packets
* If the channel specified is -1, the packet will be sent to the address in
* the `src` member of the packet.
*
- * The packet will be updated with the status of the packet after it has
- * been sent.
+ * The packet will be updated with the status of the packet after it has been
+ * sent.
*
- * \warning UDP is an _unreliable protocol_, which means we can report
+ * **Warning**: UDP is an _unreliable protocol_, which means we can report
* that your packet has been successfully sent from your machine, but then it
* never makes it to its destination when a router along the way quietly drops
* it. If this happens--and this is a common result on the internet!--you will
* not know the packet never made it. Also, packets may arrive in a different
* order than you sent them. Plan accordingly!
*
- * \warning The maximum size of the packet is limited by the MTU (Maximum
- * Transfer Unit) of the transport medium. It can be as low as 250 bytes for
- * some PPP links, and as high as 1500 bytes for ethernet. Different sizes
- * can be sent, but the system might split it into multiple transmission
- * fragments behind the scenes, that need to be reassembled on the other side
- * (and the packet is lost if any fragment is lost in transit).
- * So the less you can reasonably send in a single packet, the better, as it
- * will be more reliable and lower latency.
+ * **Warning**: The maximum size of the packet is limited by the MTU (Maximum
+ * Transfer Unit) of the transport medium. It can be as low as 250 bytes for
+ * some PPP links, and as high as 1500 bytes for ethernet. Different sizes can
+ * be sent, but the system might split it into multiple transmission fragments
+ * behind the scenes, that need to be reassembled on the other side (and the
+ * packet is lost if any fragment is lost in transit). So the less you can
+ * reasonably send in a single packet, the better, as it will be more reliable
+ * and lower latency.
*
* This function returns 1 if the packet was sent, or 0 on error.
*/
@@ -587,9 +585,9 @@ extern DECLSPEC int SDLCALL SDLNet_UDP_Send(UDPsocket sock, int channel, UDPpack
/**
* Receive a vector of pending packets from a UDP socket.
*
- * The returned packets contain the source address and the channel they arrived
- * on. If they did not arrive on a bound channel, the the channel will be set
- * to -1.
+ * The returned packets contain the source address and the channel they
+ * arrived on. If they did not arrive on a bound channel, the the channel will
+ * be set to -1.
*
* The channels are checked in highest to lowest order, so if an address is
* bound to multiple channels, the highest channel with the source address
@@ -606,8 +604,8 @@ extern DECLSPEC int SDLCALL SDLNet_UDP_Send(UDPsocket sock, int channel, UDPpack
*
* \param sock the UDP socket to receive packets on.
* \param packets an array of packets, NULL terminated.
- * \returns the number of packets read from the network, or -1 on error.
- * 0 means no packets were currently available.
+ * \returns the number of packets read from the network, or -1 on error. 0
+ * means no packets were currently available.
*
* \sa SDLNet_UDP_SendV
* \sa SDLNet_UDP_Recv
@@ -617,9 +615,9 @@ extern DECLSPEC int SDLCALL SDLNet_UDP_RecvV(UDPsocket sock, UDPpacket **packets
/**
* Receive a single packet from a UDP socket.
*
- * The returned packets contain the source address and the channel they arrived
- * on. If they did not arrive on a bound channel, the the channel will be set
- * to -1.
+ * The returned packets contain the source address and the channel they
+ * arrived on. If they did not arrive on a bound channel, the the channel will
+ * be set to -1.
*
* The channels are checked in highest to lowest order, so if an address is
* bound to multiple channels, the highest channel with the source address
@@ -630,8 +628,8 @@ extern DECLSPEC int SDLCALL SDLNet_UDP_RecvV(UDPsocket sock, UDPpacket **packets
*
* \param sock the UDP socket to receive packets on.
* \param packet a single packet to receive data into from the network.
- * \returns 1 if a new packet is available, or -1 on error.
- * 0 means no packets were currently available.
+ * \returns 1 if a new packet is available, or -1 on error. 0 means no packets
+ * were currently available.
*
* \sa SDLNet_UDP_Send
* \sa SDLNet_UDP_RecvV
@@ -664,16 +662,16 @@ typedef struct _SDLNet_GenericSocket {
/**
* Allocate a socket set for use with SDLNet_CheckSockets().
*
- * To query if new data is available on a socket, you use a "socket set"
- * with SDLNet_CheckSockets(). A socket set is just a list of sockets
- * behind the scenes; you allocate a set and then add/remove individual
- * sockets to/from the set.
+ * To query if new data is available on a socket, you use a "socket set" with
+ * SDLNet_CheckSockets(). A socket set is just a list of sockets behind the
+ * scenes; you allocate a set and then add/remove individual sockets to/from
+ * the set.
*
* When done with a socket set, you can free it with SDLNet_FreeSocketSet.
*
* \param maxsockets the maximum amount of sockets to include in this set.
- * \returns a socket set for up to `maxsockets` sockets, or NULL if
- * the function ran out of memory.
+ * \returns a socket set for up to `maxsockets` sockets, or NULL if the
+ * function ran out of memory.
*
* \sa SDLNet_FreeSocketSet
*/
@@ -690,13 +688,13 @@ extern DECLSPEC SDLNet_SocketSet SDLCALL SDLNet_AllocSocketSet(int maxsockets);
* has its maximum number of sockets added, but otherwise it will always
* succeed.
*
- * If `sock` is NULL, nothing is added to the set; this lets you query the number
- * of sockets currently contained in the set.
+ * If `sock` is NULL, nothing is added to the set; this lets you query the
+ * number of sockets currently contained in the set.
*
* \param set the socket set to add a new socket to.
* \param sock the socket to add to the set.
- * \returns the total number of sockets contained in the set (including this new one),
- * or -1 if the set is already full.
+ * \returns the total number of sockets contained in the set (including this
+ * new one), or -1 if the set is already full.
*
* \sa SDLNet_TCP_AddSocket
* \sa SDLNet_UDP_AddSocket
@@ -751,16 +749,16 @@ SDL_FORCE_INLINE int SDLNet_UDP_AddSocket(SDLNet_SocketSet set, UDPsocket sock)
* specific, inline function that wraps it: SDLNet_TCP_DelSocket() or
* SDLNet_UDP_DelSocket().
*
- * If `sock` is NULL, nothing is removed from the set; this lets you query
- * the number of sockets currently contained in the set.
+ * If `sock` is NULL, nothing is removed from the set; this lets you query the
+ * number of sockets currently contained in the set.
*
- * This will return -1 if the socket was not found in the set; in such a
- * case, nothing is removed from the set.
+ * This will return -1 if the socket was not found in the set; in such a case,
+ * nothing is removed from the set.
*
* \param set the socket set to remove a socket from.
* \param sock the socket to remove from the set.
- * \returns the total number of sockets contained in the set (after
- * `sock`'s removal), or -1 if `sock` was not in the set.
+ * \returns the total number of sockets contained in the set (after `sock`'s
+ * removal), or -1 if `sock` was not in the set.
*
* \sa SDLNet_TCP_DelSocket
* \sa SDLNet_UDP_DelSocket
@@ -810,18 +808,17 @@ SDL_FORCE_INLINE int SDLNet_UDP_DelSocket(SDLNet_SocketSet set, UDPsocket sock)
/**
* Check a socket set for data availability.
*
- * This function checks to see if data is available for reading on the
- * given set of sockets. If 'timeout' is 0, it performs a quick poll,
- * otherwise the function returns when either data is available for
- * reading, or the timeout in milliseconds has elapsed, whichever occurs
- * first.
+ * This function checks to see if data is available for reading on the given
+ * set of sockets. If 'timeout' is 0, it performs a quick poll, otherwise the
+ * function returns when either data is available for reading, or the timeout
+ * in milliseconds has elapsed, whichever occurs first.
*
* \param set the socket set to check for ready sockets.
- * \param timeout the time to wait _in milliseconds_ for new data to
- * arrive. A timeout of zero checks for new data and returns
- * without blocking.
- * \returns the number of sockets ready for reading, or -1 if there was
- * an error with the select() system call.
+ * \param timeout the time to wait _in milliseconds_ for new data to arrive. A
+ * timeout of zero checks for new data and returns without
+ * blocking.
+ * \returns the number of sockets ready for reading, or -1 if there was an
+ * error with the select() system call.
*/
extern DECLSPEC int SDLCALL SDLNet_CheckSockets(SDLNet_SocketSet set, Uint32 timeout);
@@ -845,12 +842,11 @@ SDL_FORCE_INLINE int _SDLNet_SocketReady(SDLNet_GenericSocket sock)
/**
* Free a set of sockets allocated by SDLNet_AllocSocketSet().
*
- * When done with a socket set, call this function to free its
- * resources.
+ * When done with a socket set, call this function to free its resources.
*
- * This only frees the socket set, not the individual sockets in
- * the set, which would still (at some future point) need to be
- * closed with SDLNet_TCP_Close or SDLNet_UDP_Close.
+ * This only frees the socket set, not the individual sockets in the set,
+ * which would still (at some future point) need to be closed with
+ * SDLNet_TCP_Close or SDLNet_UDP_Close.
*
* \param set the socket set to free.
*/
@@ -862,9 +858,9 @@ extern DECLSPEC void SDLCALL SDLNet_FreeSocketSet(SDLNet_SocketSet set);
/**
* Set an error message to be retrieved with SDLNe
(Patch may be truncated, please check the link at the top of this post.)