sfml3-rb 0.2.2 → 0.3.0

data/ext/network/tcp_listener.c

@@ -9,13 +9,13 @@
 #include "network/tcp_socket.h"
 
 typedef struct {
-    sfTcpListener *handle;
+    sfTcpListener* handle;
 } TcpListener;
 
 static VALUE rb_cTcpListener;
 
-static void TcpListener_free(void *ptr) {
-    TcpListener *listener = ptr;
+static void TcpListener_free(void* ptr) {
+    TcpListener* listener = ptr;
 
     if (listener->handle != NULL) {
         sfTcpListener_destroy(listener->handle);
@@ -27,11 +27,10 @@ static void TcpListener_free(void *ptr) {
 static const rb_data_type_t TcpListener_data_type = {
     .wrap_struct_name = "SFML::TcpListener",
     .function = {.dmark = NULL, .dfree = TcpListener_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
 
-static VALUE TcpListener_wrap(VALUE klass, sfTcpListener *handle) {
-    TcpListener *ptr;
+static VALUE TcpListener_wrap(VALUE klass, sfTcpListener* handle) {
+    TcpListener* ptr;
 
     if (handle == NULL) {
         rb_raise(rb_eRuntimeError, "failed to create TCP listener");
@@ -43,44 +42,100 @@ static VALUE TcpListener_wrap(VALUE klass, sfTcpListener *handle) {
     return TypedData_Wrap_Struct(klass, &TcpListener_data_type, ptr);
 }
 
+/* call-seq:
+ *   TcpListener.new -> TcpListener
+ *
+ * Creates a new TCP listener that is not yet listening.
+ *
+ * @return [TcpListener]
+ */
 static VALUE TcpListener_new(VALUE klass) {
     return TcpListener_wrap(klass, sfTcpListener_create());
 }
 
+/* call-seq:
+ *   TcpListener.any_port -> Integer
+ *
+ * Returns the port value that makes #listen bind to an OS-chosen port.
+ *
+ * @return [Integer] a port value that #listen interprets as "let the OS
+ *   pick an available port"
+ */
 static VALUE TcpListener_any_port(VALUE klass) {
     return UINT2NUM(sfTcpListener_anyPort());
 }
 
+/* call-seq: blocking? -> true or false
+ *
+ * Returns +true+ if the listener is in blocking mode.
+ *
+ * @return [Boolean]
+ */
 static VALUE TcpListener_blocking(VALUE self) {
     return BOOL2RB(sfTcpListener_isBlocking(Get_TcpListener_Struct(self)));
 }
 
+/* call-seq:
+ *   blocking=(value) -> value
+ *
+ * Enables or disables blocking mode according to +value+.
+ *
+ * @return [Boolean] +value+
+ */
 static VALUE TcpListener_set_blocking(VALUE self, VALUE rb_value) {
     sfTcpListener_setBlocking(Get_TcpListener_Struct(self), RTEST(rb_value));
     return rb_value;
 }
 
+/* call-seq: local_port -> Integer
+ *
+ * Returns the port the listener is bound to, or 0 if it isn't listening.
+ *
+ * @return [Integer] the port the listener is bound to, or 0 if it isn't
+ *   listening
+ */
 static VALUE TcpListener_local_port(VALUE self) {
     return UINT2NUM(sfTcpListener_getLocalPort(Get_TcpListener_Struct(self)));
 }
 
-static VALUE TcpListener_listen(int argc, VALUE *argv, VALUE self) {
+/* call-seq:
+ *   listen(port, address = IpAddress::ANY) -> Symbol
+ *
+ * Starts listening for incoming connections on +port+, optionally
+ * restricted to a specific local network interface via +address+.
+ *
+ * @return [Symbol] a SocketStatus name, +:done+ on success
+ */
+static VALUE TcpListener_listen(int argc, VALUE* argv, VALUE self) {
     VALUE rb_port, rb_address;
 
     rb_scan_args(argc, argv, "11", &rb_port, &rb_address);
 
-    return ID2SYM(rb_intern(socket_status_name(sfTcpListener_listen(
-        Get_TcpListener_Struct(self), (unsigned short) NUM2INT(rb_port),
-        ip_address_from_rb(rb_address, sfIpAddress_Any)))));
+    return ID2SYM(rb_intern(socket_status_name(
+        sfTcpListener_listen(Get_TcpListener_Struct(self), (unsigned short)NUM2INT(rb_port),
+                             ip_address_from_rb(rb_address, sfIpAddress_Any)))));
 }
 
+/* call-seq: close -> self
+ *
+ * Stops listening and closes the underlying socket.
+ *
+ * @return [self]
+ */
 static VALUE TcpListener_close(VALUE self) {
     sfTcpListener_close(Get_TcpListener_Struct(self));
     return self;
 }
 
+/* call-seq: accept -> [TcpSocket, Symbol]
+ *
+ * Blocks (unless #blocking? is +false+) waiting for a client to connect.
+ *
+ * @return [Array(TcpSocket, Symbol)] the connected socket (or +nil+ if the
+ *   status isn't +:done+), and a SocketStatus name
+ */
 static VALUE TcpListener_accept(VALUE self) {
-    sfTcpSocket *socket = NULL;
+    sfTcpSocket* socket = NULL;
     sfSocketStatus status = sfTcpListener_accept(Get_TcpListener_Struct(self), &socket);
     VALUE rb_result = rb_ary_new_capa(2);
 
@@ -90,8 +145,12 @@ static VALUE TcpListener_accept(VALUE self) {
     return rb_result;
 }
 
-void Init_TcpListener(VALUE rb_module) {
-    rb_cTcpListener = rb_define_class_under(rb_module, "TcpListener", rb_cObject);
+/* Document-class: SFML::TcpListener
+ * Listens for and accepts incoming TCP connections, producing connected
+ * TcpSocket instances.
+ */
+void Init_TcpListener(VALUE rb_mSFML) {
+    rb_cTcpListener = rb_define_class_under(rb_mSFML, "TcpListener", rb_cObject);
 
     rb_define_singleton_method(rb_cTcpListener, "new", TcpListener_new, 0);
     rb_define_singleton_method(rb_cTcpListener, "any_port", TcpListener_any_port, 0);
@@ -108,8 +167,8 @@ VALUE Get_Klass_TcpListener(void) {
     return rb_cTcpListener;
 }
 
-void *Get_TcpListener_Struct(VALUE self) {
-    TcpListener *ptr;
+void* Get_TcpListener_Struct(VALUE self) {
+    TcpListener* ptr;
     TypedData_Get_Struct(self, TcpListener, &TcpListener_data_type, ptr);
     return ptr->handle;
 }

data/ext/network/tcp_socket.c

@@ -10,13 +10,13 @@
 #include "system/time.h"
 
 typedef struct {
-    sfTcpSocket *handle;
+    sfTcpSocket* handle;
 } TcpSocket;
 
 static VALUE rb_cTcpSocket;
 
-static void TcpSocket_free(void *ptr) {
-    TcpSocket *socket = ptr;
+static void TcpSocket_free(void* ptr) {
+    TcpSocket* socket = ptr;
 
     if (socket->handle != NULL) {
         sfTcpSocket_destroy(socket->handle);
@@ -28,11 +28,10 @@ static void TcpSocket_free(void *ptr) {
 static const rb_data_type_t TcpSocket_data_type = {
     .wrap_struct_name = "SFML::TcpSocket",
     .function = {.dmark = NULL, .dfree = TcpSocket_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
 
-static VALUE TcpSocket_wrap(VALUE klass, sfTcpSocket *handle) {
-    TcpSocket *ptr;
+static VALUE TcpSocket_wrap(VALUE klass, sfTcpSocket* handle) {
+    TcpSocket* ptr;
 
     if (handle == NULL) {
         rb_raise(rb_eRuntimeError, "failed to create TCP socket");
@@ -44,36 +43,84 @@ static VALUE TcpSocket_wrap(VALUE klass, sfTcpSocket *handle) {
     return TypedData_Wrap_Struct(klass, &TcpSocket_data_type, ptr);
 }
 
-VALUE tcp_socket_from_handle(sfTcpSocket *socket) {
+VALUE tcp_socket_from_handle(sfTcpSocket* socket) {
     return TcpSocket_wrap(rb_cTcpSocket, socket);
 }
 
+/* call-seq:
+ *   TcpSocket.new -> TcpSocket
+ *
+ * Creates a new, unconnected TCP socket.
+ *
+ * @return [TcpSocket] a new, unconnected socket
+ */
 static VALUE TcpSocket_new(VALUE klass) {
     return TcpSocket_wrap(klass, sfTcpSocket_create());
 }
 
+/* call-seq: blocking? -> true or false
+ *
+ * Returns +true+ if the socket is in blocking mode.
+ *
+ * @return [Boolean]
+ */
 static VALUE TcpSocket_blocking(VALUE self) {
     return BOOL2RB(sfTcpSocket_isBlocking(Get_TcpSocket_Struct(self)));
 }
 
+/* call-seq:
+ *   blocking=(value) -> value
+ *
+ * Enables or disables blocking mode according to +value+.
+ *
+ * @return [Boolean] +value+
+ */
 static VALUE TcpSocket_set_blocking(VALUE self, VALUE rb_value) {
     sfTcpSocket_setBlocking(Get_TcpSocket_Struct(self), RTEST(rb_value));
     return rb_value;
 }
 
+/* call-seq: local_port -> Integer
+ *
+ * Returns the local port the socket is bound to.
+ *
+ * @return [Integer] the local port the socket is bound to, or 0 if it
+ *   isn't connected
+ */
 static VALUE TcpSocket_local_port(VALUE self) {
     return UINT2NUM(sfTcpSocket_getLocalPort(Get_TcpSocket_Struct(self)));
 }
 
+/* call-seq: remote_address -> IpAddress
+ *
+ * Returns the address of the remote peer.
+ *
+ * @return [IpAddress] the address of the remote peer, or +IpAddress::NONE+
+ *   if not connected
+ */
 static VALUE TcpSocket_remote_address(VALUE self) {
     return ip_address_to_rb(sfTcpSocket_getRemoteAddress(Get_TcpSocket_Struct(self)));
 }
 
+/* call-seq: remote_port -> Integer
+ *
+ * Returns the port of the remote peer.
+ *
+ * @return [Integer] the port of the remote peer, or 0 if not connected
+ */
 static VALUE TcpSocket_remote_port(VALUE self) {
     return UINT2NUM(sfTcpSocket_getRemotePort(Get_TcpSocket_Struct(self)));
 }
 
-static VALUE TcpSocket_connect(int argc, VALUE *argv, VALUE self) {
+/* call-seq:
+ *   connect(address, port, timeout = Time.zero) -> Symbol
+ *
+ * Connects to a remote peer, blocking (unless #blocking? is +false+) until
+ * connected or +timeout+ elapses.
+ *
+ * @return [Symbol] a SocketStatus name, +:done+ on success
+ */
+static VALUE TcpSocket_connect(int argc, VALUE* argv, VALUE self) {
     VALUE rb_address, rb_port, rb_timeout;
     sfTime timeout = sfTime_Zero;
 
@@ -85,22 +132,45 @@ static VALUE TcpSocket_connect(int argc, VALUE *argv, VALUE self) {
 
     return ID2SYM(rb_intern(socket_status_name(sfTcpSocket_connect(
         Get_TcpSocket_Struct(self), ip_address_from_rb(rb_address, sfIpAddress_None),
-        (unsigned short) NUM2INT(rb_port), timeout))));
+        (unsigned short)NUM2INT(rb_port), timeout))));
 }
 
+/* call-seq: disconnect -> self
+ *
+ * Closes the connection.
+ *
+ * @return [self]
+ */
 static VALUE TcpSocket_disconnect(VALUE self) {
     sfTcpSocket_disconnect(Get_TcpSocket_Struct(self));
     return self;
 }
 
+/* call-seq:
+ *   send(data) -> Symbol
+ *
+ * Sends the full contents of +data+, blocking (unless #blocking? is
+ * +false+) until it is all sent. Prefer #send_partial for non-blocking
+ * sockets, since this can return +:not_ready+ having sent only part of
+ * the data with no way to know how much.
+ *
+ * @return [Symbol] a SocketStatus name, +:done+ on success
+ */
 static VALUE TcpSocket_send(VALUE self, VALUE rb_data) {
     StringValue(rb_data);
 
-    return ID2SYM(rb_intern(socket_status_name(
-        sfTcpSocket_send(Get_TcpSocket_Struct(self), RSTRING_PTR(rb_data),
-                         (size_t) RSTRING_LEN(rb_data)))));
+    return ID2SYM(rb_intern(socket_status_name(sfTcpSocket_send(
+        Get_TcpSocket_Struct(self), RSTRING_PTR(rb_data), (size_t)RSTRING_LEN(rb_data)))));
 }
 
+/* call-seq:
+ *   send_partial(data) -> [Integer, Symbol]
+ *
+ * Like #send, but may send only part of +data+ and reports how much.
+ *
+ * @return [Array(Integer, Symbol)] the number of bytes actually sent, and
+ *   a SocketStatus name
+ */
 static VALUE TcpSocket_send_partial(VALUE self, VALUE rb_data) {
     size_t sent = 0;
     sfSocketStatus status;
@@ -109,7 +179,7 @@ static VALUE TcpSocket_send_partial(VALUE self, VALUE rb_data) {
     StringValue(rb_data);
 
     status = sfTcpSocket_sendPartial(Get_TcpSocket_Struct(self), RSTRING_PTR(rb_data),
-                                     (size_t) RSTRING_LEN(rb_data), &sent);
+                                     (size_t)RSTRING_LEN(rb_data), &sent);
 
     rb_result = rb_ary_new_capa(2);
     rb_ary_push(rb_result, SIZET2NUM(sent));
@@ -118,12 +188,19 @@ static VALUE TcpSocket_send_partial(VALUE self, VALUE rb_data) {
     return rb_result;
 }
 
-/* Receive needs a maximum size up front because CSFML fills a caller buffer.
-   Returns [data, status], where data is empty unless the status is :done. */
-static VALUE TcpSocket_receive(int argc, VALUE *argv, VALUE self) {
+/* call-seq:
+ *   receive(max_length = 1024) -> [String, Symbol]
+ *
+ * Receive needs a maximum size up front because CSFML fills a caller buffer.
+ * Returns [data, status], where data is empty unless the status is :done.
+ *
+ * @return [Array(String, Symbol)] the bytes received, and a SocketStatus name
+ * @raise [ArgumentError] if +max_length+ isn't positive
+ */
+static VALUE TcpSocket_receive(int argc, VALUE* argv, VALUE self) {
     VALUE rb_max_length;
     long max_length = 1024;
-    char *buffer;
+    char* buffer;
     size_t received = 0;
     sfSocketStatus status;
     VALUE rb_result;
@@ -138,12 +215,16 @@ static VALUE TcpSocket_receive(int argc, VALUE *argv, VALUE self) {
         rb_raise(rb_eArgError, "maximum length must be positive");
     }
 
-    buffer = malloc((size_t) max_length);
+    buffer = malloc((size_t)max_length);
+
+    if (buffer == NULL) {
+        rb_raise(rb_eNoMemError, "failed to allocate receive buffer");
+    }
 
-    status = sfTcpSocket_receive(Get_TcpSocket_Struct(self), buffer, (size_t) max_length, &received);
+    status = sfTcpSocket_receive(Get_TcpSocket_Struct(self), buffer, (size_t)max_length, &received);
 
     rb_result = rb_ary_new_capa(2);
-    rb_ary_push(rb_result, rb_str_new(buffer, (long) received));
+    rb_ary_push(rb_result, rb_str_new(buffer, (long)received));
     rb_ary_push(rb_result, ID2SYM(rb_intern(socket_status_name(status))));
 
     free(buffer);
@@ -151,6 +232,14 @@ static VALUE TcpSocket_receive(int argc, VALUE *argv, VALUE self) {
     return rb_result;
 }
 
+/* call-seq:
+ *   send_packet(packet) -> Symbol
+ *
+ * Sends +packet+ over the connection.
+ *
+ * @return [Symbol] a SocketStatus name, +:done+ on success
+ * @raise [TypeError] if +packet+ is not an SFML::Packet
+ */
 static VALUE TcpSocket_send_packet(VALUE self, VALUE rb_packet) {
     if (!rb_obj_is_kind_of(rb_packet, Get_Klass_Packet())) {
         rb_raise(rb_eTypeError, "expected an SFML::Packet");
@@ -160,6 +249,15 @@ static VALUE TcpSocket_send_packet(VALUE self, VALUE rb_packet) {
         sfTcpSocket_sendPacket(Get_TcpSocket_Struct(self), Get_Packet_Struct(rb_packet)))));
 }
 
+/* call-seq:
+ *   receive_packet(packet) -> Symbol
+ *
+ * Fills +packet+ (replacing its previous contents) with the next packet
+ * received.
+ *
+ * @return [Symbol] a SocketStatus name, +:done+ on success
+ * @raise [TypeError] if +packet+ is not an SFML::Packet
+ */
 static VALUE TcpSocket_receive_packet(VALUE self, VALUE rb_packet) {
     if (!rb_obj_is_kind_of(rb_packet, Get_Klass_Packet())) {
         rb_raise(rb_eTypeError, "expected an SFML::Packet");
@@ -169,8 +267,13 @@ static VALUE TcpSocket_receive_packet(VALUE self, VALUE rb_packet) {
         sfTcpSocket_receivePacket(Get_TcpSocket_Struct(self), Get_Packet_Struct(rb_packet)))));
 }
 
-void Init_TcpSocket(VALUE rb_module) {
-    rb_cTcpSocket = rb_define_class_under(rb_module, "TcpSocket", rb_cObject);
+/* Document-class: SFML::TcpSocket
+ * A connection-oriented, reliable, byte-stream socket for TCP communication.
+ * Connect with #connect (or receive one already connected from
+ * TcpListener#accept), then send/receive raw bytes or Packet instances.
+ */
+void Init_TcpSocket(VALUE rb_mSFML) {
+    rb_cTcpSocket = rb_define_class_under(rb_mSFML, "TcpSocket", rb_cObject);
 
     rb_define_singleton_method(rb_cTcpSocket, "new", TcpSocket_new, 0);
 
@@ -192,8 +295,8 @@ VALUE Get_Klass_TcpSocket(void) {
     return rb_cTcpSocket;
 }
 
-void *Get_TcpSocket_Struct(VALUE self) {
-    TcpSocket *ptr;
+void* Get_TcpSocket_Struct(VALUE self) {
+    TcpSocket* ptr;
     TypedData_Get_Struct(self, TcpSocket, &TcpSocket_data_type, ptr);
     return ptr->handle;
 }

data/ext/network/udp_socket.c

@@ -9,13 +9,13 @@
 #include "network/packet.h"
 
 typedef struct {
-    sfUdpSocket *handle;
+    sfUdpSocket* handle;
 } UdpSocket;
 
 static VALUE rb_cUdpSocket;
 
-static void UdpSocket_free(void *ptr) {
-    UdpSocket *socket = ptr;
+static void UdpSocket_free(void* ptr) {
+    UdpSocket* socket = ptr;
 
     if (socket->handle != NULL) {
         sfUdpSocket_destroy(socket->handle);
@@ -27,11 +27,10 @@ static void UdpSocket_free(void *ptr) {
 static const rb_data_type_t UdpSocket_data_type = {
     .wrap_struct_name = "SFML::UdpSocket",
     .function = {.dmark = NULL, .dfree = UdpSocket_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
 
-static VALUE UdpSocket_wrap(VALUE klass, sfUdpSocket *handle) {
-    UdpSocket *ptr;
+static VALUE UdpSocket_wrap(VALUE klass, sfUdpSocket* handle) {
+    UdpSocket* ptr;
 
     if (handle == NULL) {
         rb_raise(rb_eRuntimeError, "failed to create UDP socket");
@@ -43,60 +42,131 @@ static VALUE UdpSocket_wrap(VALUE klass, sfUdpSocket *handle) {
     return TypedData_Wrap_Struct(klass, &UdpSocket_data_type, ptr);
 }
 
+/* call-seq:
+ *   UdpSocket.new -> UdpSocket
+ *
+ * Creates a new, unbound UDP socket.
+ *
+ * @return [UdpSocket] a new, unbound socket
+ */
 static VALUE UdpSocket_new(VALUE klass) {
     return UdpSocket_wrap(klass, sfUdpSocket_create());
 }
 
+/* call-seq:
+ *   UdpSocket.any_port -> Integer
+ *
+ * Returns the port value that makes #bind bind to an OS-chosen port.
+ *
+ * @return [Integer] a port value that #bind interprets as "let the OS pick
+ *   an available port"
+ */
 static VALUE UdpSocket_any_port(VALUE klass) {
     return UINT2NUM(sfUdpSocket_anyPort());
 }
 
+/* call-seq:
+ *   UdpSocket.max_datagram_size -> Integer
+ *
+ * Returns the maximum size, in bytes, of a single UDP datagram.
+ *
+ * @return [Integer] the maximum number of bytes that can be sent in a
+ *   single UDP datagram (65507)
+ */
 static VALUE UdpSocket_max_datagram_size(VALUE klass) {
     return UINT2NUM(sfUdpSocket_maxDatagramSize());
 }
 
+/* call-seq: blocking? -> true or false
+ *
+ * Returns +true+ if the socket is in blocking mode.
+ *
+ * @return [Boolean]
+ */
 static VALUE UdpSocket_blocking(VALUE self) {
     return BOOL2RB(sfUdpSocket_isBlocking(Get_UdpSocket_Struct(self)));
 }
 
+/* call-seq:
+ *   blocking=(value) -> value
+ *
+ * Enables or disables blocking mode according to +value+.
+ *
+ * @return [Boolean] +value+
+ */
 static VALUE UdpSocket_set_blocking(VALUE self, VALUE rb_value) {
     sfUdpSocket_setBlocking(Get_UdpSocket_Struct(self), RTEST(rb_value));
     return rb_value;
 }
 
+/* call-seq: local_port -> Integer
+ *
+ * Returns the local port the socket is bound to.
+ *
+ * @return [Integer] the port the socket is bound to, or 0 if not bound
+ */
 static VALUE UdpSocket_local_port(VALUE self) {
     return UINT2NUM(sfUdpSocket_getLocalPort(Get_UdpSocket_Struct(self)));
 }
 
-static VALUE UdpSocket_bind(int argc, VALUE *argv, VALUE self) {
+/* call-seq:
+ *   bind(port, address = IpAddress::ANY) -> Symbol
+ *
+ * Binds the socket to a local port, optionally restricted to a specific
+ * local network interface via +address+, so it can receive datagrams.
+ *
+ * @return [Symbol] a SocketStatus name, +:done+ on success
+ */
+static VALUE UdpSocket_bind(int argc, VALUE* argv, VALUE self) {
     VALUE rb_port, rb_address;
 
     rb_scan_args(argc, argv, "11", &rb_port, &rb_address);
 
-    return ID2SYM(rb_intern(socket_status_name(sfUdpSocket_bind(
-        Get_UdpSocket_Struct(self), (unsigned short) NUM2INT(rb_port),
-        ip_address_from_rb(rb_address, sfIpAddress_Any)))));
+    return ID2SYM(rb_intern(socket_status_name(
+        sfUdpSocket_bind(Get_UdpSocket_Struct(self), (unsigned short)NUM2INT(rb_port),
+                         ip_address_from_rb(rb_address, sfIpAddress_Any)))));
 }
 
+/* call-seq: unbind -> self
+ *
+ * Unbinds the socket from its local port.
+ *
+ * @return [self]
+ */
 static VALUE UdpSocket_unbind(VALUE self) {
     sfUdpSocket_unbind(Get_UdpSocket_Struct(self));
     return self;
 }
 
+/* call-seq:
+ *   send(data, address, port) -> Symbol
+ *
+ * Sends a single datagram to a remote peer. +data+ must be no larger than
+ * .max_datagram_size bytes.
+ *
+ * @return [Symbol] a SocketStatus name, +:done+ on success
+ */
 static VALUE UdpSocket_send(VALUE self, VALUE rb_data, VALUE rb_address, VALUE rb_port) {
     StringValue(rb_data);
 
     return ID2SYM(rb_intern(socket_status_name(sfUdpSocket_send(
-        Get_UdpSocket_Struct(self), RSTRING_PTR(rb_data), (size_t) RSTRING_LEN(rb_data),
-        ip_address_from_rb(rb_address, sfIpAddress_None), (unsigned short) NUM2INT(rb_port)))));
+        Get_UdpSocket_Struct(self), RSTRING_PTR(rb_data), (size_t)RSTRING_LEN(rb_data),
+        ip_address_from_rb(rb_address, sfIpAddress_None), (unsigned short)NUM2INT(rb_port)))));
 }
 
-/* Returns [data, IpAddress, port, status]; the address and port are those of
-   the sender. */
-static VALUE UdpSocket_receive(int argc, VALUE *argv, VALUE self) {
+/* call-seq:
+ *   receive(max_length = 1024) -> [String, IpAddress, Integer, Symbol]
+ *
+ * Returns [data, IpAddress, port, status]; the address and port are those of
+ * the sender.
+ *
+ * @return [Array(String, IpAddress, Integer, Symbol)]
+ * @raise [ArgumentError] if +max_length+ isn't positive
+ */
+static VALUE UdpSocket_receive(int argc, VALUE* argv, VALUE self) {
     VALUE rb_max_length;
     long max_length = 1024;
-    char *buffer;
+    char* buffer;
     size_t received = 0;
     sfIpAddress remote_address = sfIpAddress_None;
     unsigned short remote_port = 0;
@@ -113,13 +183,17 @@ static VALUE UdpSocket_receive(int argc, VALUE *argv, VALUE self) {
         rb_raise(rb_eArgError, "maximum length must be positive");
     }
 
-    buffer = malloc((size_t) max_length);
+    buffer = malloc((size_t)max_length);
 
-    status = sfUdpSocket_receive(Get_UdpSocket_Struct(self), buffer, (size_t) max_length, &received,
+    if (buffer == NULL) {
+        rb_raise(rb_eNoMemError, "failed to allocate receive buffer");
+    }
+
+    status = sfUdpSocket_receive(Get_UdpSocket_Struct(self), buffer, (size_t)max_length, &received,
                                  &remote_address, &remote_port);
 
     rb_result = rb_ary_new_capa(4);
-    rb_ary_push(rb_result, rb_str_new(buffer, (long) received));
+    rb_ary_push(rb_result, rb_str_new(buffer, (long)received));
     rb_ary_push(rb_result, ip_address_to_rb(remote_address));
     rb_ary_push(rb_result, UINT2NUM(remote_port));
     rb_ary_push(rb_result, ID2SYM(rb_intern(socket_status_name(status))));
@@ -129,6 +203,14 @@ static VALUE UdpSocket_receive(int argc, VALUE *argv, VALUE self) {
     return rb_result;
 }
 
+/* call-seq:
+ *   send_packet(packet, address, port) -> Symbol
+ *
+ * Sends +packet+ as a datagram to the given +address+ and +port+.
+ *
+ * @return [Symbol] a SocketStatus name, +:done+ on success
+ * @raise [TypeError] if +packet+ is not an SFML::Packet
+ */
 static VALUE UdpSocket_send_packet(VALUE self, VALUE rb_packet, VALUE rb_address, VALUE rb_port) {
     if (!rb_obj_is_kind_of(rb_packet, Get_Klass_Packet())) {
         rb_raise(rb_eTypeError, "expected an SFML::Packet");
@@ -136,10 +218,19 @@ static VALUE UdpSocket_send_packet(VALUE self, VALUE rb_packet, VALUE rb_address
 
     return ID2SYM(rb_intern(socket_status_name(sfUdpSocket_sendPacket(
         Get_UdpSocket_Struct(self), Get_Packet_Struct(rb_packet),
-        ip_address_from_rb(rb_address, sfIpAddress_None), (unsigned short) NUM2INT(rb_port)))));
+        ip_address_from_rb(rb_address, sfIpAddress_None), (unsigned short)NUM2INT(rb_port)))));
 }
 
-/* Returns [IpAddress, port, status]. */
+/* call-seq:
+ *   receive_packet(packet) -> [IpAddress, Integer, Symbol]
+ *
+ * Fills +packet+ (replacing its previous contents) with the next datagram
+ * received. Returns [IpAddress, port, status], the address and port of the
+ * sender.
+ *
+ * @return [Array(IpAddress, Integer, Symbol)]
+ * @raise [TypeError] if +packet+ is not an SFML::Packet
+ */
 static VALUE UdpSocket_receive_packet(VALUE self, VALUE rb_packet) {
     sfIpAddress remote_address = sfIpAddress_None;
     unsigned short remote_port = 0;
@@ -161,8 +252,13 @@ static VALUE UdpSocket_receive_packet(VALUE self, VALUE rb_packet) {
     return rb_result;
 }
 
-void Init_UdpSocket(VALUE rb_module) {
-    rb_cUdpSocket = rb_define_class_under(rb_module, "UdpSocket", rb_cObject);
+/* Document-class: SFML::UdpSocket
+ * A connectionless, unreliable, datagram-oriented socket for UDP
+ * communication. Datagrams may be lost, duplicated or arrive out of order,
+ * and are capped at .max_datagram_size bytes.
+ */
+void Init_UdpSocket(VALUE rb_mSFML) {
+    rb_cUdpSocket = rb_define_class_under(rb_mSFML, "UdpSocket", rb_cObject);
 
     rb_define_singleton_method(rb_cUdpSocket, "new", UdpSocket_new, 0);
     rb_define_singleton_method(rb_cUdpSocket, "any_port", UdpSocket_any_port, 0);
@@ -183,8 +279,8 @@ VALUE Get_Klass_UdpSocket(void) {
     return rb_cUdpSocket;
 }
 
-void *Get_UdpSocket_Struct(VALUE self) {
-    UdpSocket *ptr;
+void* Get_UdpSocket_Struct(VALUE self) {
+    UdpSocket* ptr;
     TypedData_Get_Struct(self, UdpSocket, &UdpSocket_data_type, ptr);
     return ptr->handle;
 }