sfml3-rb 0.2.2 → 0.3.0

data/ext/graphics/font.c

@@ -10,17 +10,16 @@
 
 static VALUE rb_cFont;
 
-static void Font_free(void *ptr) {
+static void Font_free(void* ptr) {
     sfFont_destroy(ptr);
 }
 
 static const rb_data_type_t Font_data_type = {
     .wrap_struct_name = "SFML::Font",
     .function = {.dmark = NULL, .dfree = Font_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
 
-static VALUE Font_wrap(VALUE klass, sfFont *font) {
+static VALUE Font_wrap(VALUE klass, sfFont* font) {
     if (font == NULL) {
         rb_raise(rb_eRuntimeError, "failed to load font");
     }
@@ -28,30 +27,69 @@ static VALUE Font_wrap(VALUE klass, sfFont *font) {
     return TypedData_Wrap_Struct(klass, &Font_data_type, font);
 }
 
+/* call-seq:
+ *   Font.from_file(path) -> Font
+ *
+ * Loads a font from the font file at +filename+.
+ *
+ * @return [Font]
+ * @raise [RuntimeError] if the file cannot be loaded
+ */
 static VALUE Font_from_file(VALUE klass, VALUE rb_path) {
     return Font_wrap(klass, sfFont_createFromFile(StringValueCStr(rb_path)));
 }
 
+/* call-seq:
+ *   Font.from_memory(data) -> Font
+ *
+ * Loads a font from an in-memory font file buffer.
+ *
+ * @return [Font]
+ * @raise [RuntimeError] if the font data cannot be parsed
+ */
 static VALUE Font_from_memory(VALUE klass, VALUE rb_data) {
     StringValue(rb_data);
 
-    return Font_wrap(klass, sfFont_createFromMemory(RSTRING_PTR(rb_data), (size_t) RSTRING_LEN(rb_data)));
+    return Font_wrap(klass,
+                     sfFont_createFromMemory(RSTRING_PTR(rb_data), (size_t)RSTRING_LEN(rb_data)));
 }
 
+/* call-seq:
+ *   Font.from_stream(stream) -> Font
+ *
+ * +stream+ is any object responding to the InputStream protocol (see
+ * InputStream).
+ *
+ * @return [Font]
+ * @raise [RuntimeError] if the font cannot be loaded
+ */
 static VALUE Font_from_stream(VALUE klass, VALUE rb_stream) {
     VALUE holder = Qnil;
-    sfInputStream *stream = input_stream_from_rb(rb_stream, &holder);
+    sfInputStream* stream = input_stream_from_rb(rb_stream, &holder);
 
-    (void) holder;
+    (void)holder;
 
     return Font_wrap(klass, sfFont_createFromStream(stream));
 }
 
+/* call-seq: copy -> Font
+ *
+ * Returns a deep copy of the object.
+ *
+ * @return [Font] an independent copy
+ */
 static VALUE Font_copy(VALUE self) {
     return Font_wrap(Get_Klass_Font(), sfFont_copy(Get_Font_Struct(self)));
 }
 
-static VALUE Font_get_glyph(int argc, VALUE *argv, VALUE self) {
+/* call-seq:
+ *   glyph(codepoint, size, bold=false, outline_thickness=0) -> Glyph
+ *
+ * Returns the glyph for +codepoint+ at the given +character_size+.
+ *
+ * @return [Glyph]
+ */
+static VALUE Font_get_glyph(int argc, VALUE* argv, VALUE self) {
     VALUE rb_codepoint, rb_size, rb_bold, rb_outline;
     bool bold = false;
     float outline = 0;
@@ -66,58 +104,133 @@ static VALUE Font_get_glyph(int argc, VALUE *argv, VALUE self) {
         outline = NUM2DBL(rb_outline);
     }
 
-    return glyph_from_c(sfFont_getGlyph(Get_Font_Struct(self), (uint32_t) NUM2UINT(rb_codepoint),
-                                        (unsigned int) NUM2UINT(rb_size), bold, outline));
+    return glyph_from_c(sfFont_getGlyph(Get_Font_Struct(self), (uint32_t)NUM2UINT(rb_codepoint),
+                                        (unsigned int)NUM2UINT(rb_size), bold, outline));
 }
 
+/* call-seq: has_glyph?(codepoint) -> true or false
+ *
+ * Returns +true+ if the font contains a glyph for +codepoint+.
+ *
+ * @return [Boolean] whether this font has a glyph for the given Unicode
+ *   codepoint
+ */
 static VALUE Font_has_glyph(VALUE self, VALUE rb_codepoint) {
-    return BOOL2RB(sfFont_hasGlyph(Get_Font_Struct(self), (uint32_t) NUM2UINT(rb_codepoint)));
+    return BOOL2RB(sfFont_hasGlyph(Get_Font_Struct(self), (uint32_t)NUM2UINT(rb_codepoint)));
 }
 
+/* call-seq: kerning(first, second, size) -> Float
+ *
+ * Returns the kerning between two code points at the given size.
+ *
+ * @return [Float] the kerning offset between two consecutive glyphs at the
+ *   given character size
+ */
 static VALUE Font_get_kerning(VALUE self, VALUE rb_first, VALUE rb_second, VALUE rb_size) {
-    return DBL2NUM(sfFont_getKerning(Get_Font_Struct(self), (uint32_t) NUM2UINT(rb_first),
-                                     (uint32_t) NUM2UINT(rb_second), (unsigned int) NUM2UINT(rb_size)));
+    return DBL2NUM(sfFont_getKerning(Get_Font_Struct(self), (uint32_t)NUM2UINT(rb_first),
+                                     (uint32_t)NUM2UINT(rb_second),
+                                     (unsigned int)NUM2UINT(rb_size)));
 }
 
+/* call-seq: bold_kerning(first, second, size) -> Float
+ *
+ * Returns the kerning of the bold variant between two code points.
+ *
+ * @return [Float] the kerning offset between two consecutive bold glyphs at
+ *   the given character size
+ */
 static VALUE Font_get_bold_kerning(VALUE self, VALUE rb_first, VALUE rb_second, VALUE rb_size) {
-    return DBL2NUM(sfFont_getBoldKerning(Get_Font_Struct(self), (uint32_t) NUM2UINT(rb_first),
-                                         (uint32_t) NUM2UINT(rb_second), (unsigned int) NUM2UINT(rb_size)));
+    return DBL2NUM(sfFont_getBoldKerning(Get_Font_Struct(self), (uint32_t)NUM2UINT(rb_first),
+                                         (uint32_t)NUM2UINT(rb_second),
+                                         (unsigned int)NUM2UINT(rb_size)));
 }
 
+/* call-seq: line_spacing(size) -> Float
+ *
+ * Returns the line spacing for the given character size.
+ *
+ * @return [Float] the distance between two consecutive lines at the given
+ *   character size
+ */
 static VALUE Font_get_line_spacing(VALUE self, VALUE rb_size) {
-    return DBL2NUM(sfFont_getLineSpacing(Get_Font_Struct(self), (unsigned int) NUM2UINT(rb_size)));
+    return DBL2NUM(sfFont_getLineSpacing(Get_Font_Struct(self), (unsigned int)NUM2UINT(rb_size)));
 }
 
+/* call-seq: underline_position(size) -> Float
+ *
+ * Returns the position of the underline for the given size.
+ *
+ * @return [Float] the position of the underline, relative to the baseline,
+ *   at the given character size
+ */
 static VALUE Font_get_underline_position(VALUE self, VALUE rb_size) {
-    return DBL2NUM(sfFont_getUnderlinePosition(Get_Font_Struct(self), (unsigned int) NUM2UINT(rb_size)));
+    return DBL2NUM(
+        sfFont_getUnderlinePosition(Get_Font_Struct(self), (unsigned int)NUM2UINT(rb_size)));
 }
 
+/* call-seq: underline_thickness(size) -> Float
+ *
+ * Returns the thickness of the underline for the given size.
+ *
+ * @return [Float] the thickness of the underline at the given character size
+ */
 static VALUE Font_get_underline_thickness(VALUE self, VALUE rb_size) {
-    return DBL2NUM(sfFont_getUnderlineThickness(Get_Font_Struct(self), (unsigned int) NUM2UINT(rb_size)));
+    return DBL2NUM(
+        sfFont_getUnderlineThickness(Get_Font_Struct(self), (unsigned int)NUM2UINT(rb_size)));
 }
 
+/* call-seq: texture(size) -> Texture
+ *
+ * Returns the texture atlas holding rendered glyphs for the given size.
+ *
+ * @return [Texture] the texture atlas holding rendered glyphs for the given
+ *   character size. Owned by the font; do not modify or free it directly.
+ */
 static VALUE Font_get_texture(VALUE self, VALUE rb_size) {
-    return texture_from_borrowed(sfFont_getTexture((sfFont *) Get_Font_Struct(self),
-                                                   (unsigned int) NUM2UINT(rb_size)));
+    return texture_from_borrowed(
+        sfFont_getTexture((sfFont*)Get_Font_Struct(self), (unsigned int)NUM2UINT(rb_size)));
 }
 
+/* call-seq:
+ *   smooth=(value) -> Boolean
+ *
+ * Enables or disables smooth rendering.
+ *
+ * @return [Boolean] +value+
+ */
 static VALUE Font_set_smooth(VALUE self, VALUE rb_smooth) {
-    sfFont_setSmooth((sfFont *) Get_Font_Struct(self), RTEST(rb_smooth));
+    sfFont_setSmooth((sfFont*)Get_Font_Struct(self), RTEST(rb_smooth));
     return rb_smooth;
 }
 
+/* call-seq: smooth? -> true or false
+ *
+ * Returns +true+ if smooth rendering is enabled.
+ *
+ * @return [Boolean]
+ */
 static VALUE Font_is_smooth(VALUE self) {
     return BOOL2RB(sfFont_isSmooth(Get_Font_Struct(self)));
 }
 
+/* call-seq: info -> String
+ *
+ * Returns the font's family name.
+ *
+ * @return [String] the font family name
+ */
 static VALUE Font_get_info(VALUE self) {
     sfFontInfo info = sfFont_getInfo(Get_Font_Struct(self));
 
     return rb_str_new_cstr(info.family != NULL ? info.family : "");
 }
 
-void Init_Font(VALUE rb_module) {
-    rb_cFont = rb_define_class_under(rb_module, "Font", rb_cObject);
+/* Document-class: SFML::Font
+ * A font face used to render text, loaded from a file, memory buffer or
+ * stream. Glyphs are rasterized and cached lazily per character size.
+ */
+void Init_Font(VALUE rb_mSFML) {
+    rb_cFont = rb_define_class_under(rb_mSFML, "Font", rb_cObject);
 
     rb_define_singleton_method(rb_cFont, "from_file", Font_from_file, 1);
     rb_define_singleton_method(rb_cFont, "from_memory", Font_from_memory, 1);
@@ -141,8 +254,8 @@ VALUE Get_Klass_Font(void) {
     return rb_cFont;
 }
 
-const sfFont *Get_Font_Struct(VALUE self) {
-    sfFont *ptr;
+const sfFont* Get_Font_Struct(VALUE self) {
+    sfFont* ptr;
     TypedData_Get_Struct(self, sfFont, &Font_data_type, ptr);
     return ptr;
 }

data/ext/graphics/glyph.c

@@ -11,44 +11,67 @@ typedef struct {
 
 static VALUE rb_cGlyph;
 
-static void Glyph_free(void *ptr) {
+static void Glyph_free(void* ptr) {
     free(ptr);
 }
 
 static const rb_data_type_t Glyph_data_type = {
     .wrap_struct_name = "SFML::Glyph",
     .function = {.dmark = NULL, .dfree = Glyph_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
 
 VALUE glyph_from_c(sfGlyph glyph) {
-    Glyph *ptr = malloc(sizeof(Glyph));
+    Glyph* ptr = malloc(sizeof(Glyph));
 
     ptr->glyph = glyph;
 
     return TypedData_Wrap_Struct(rb_cGlyph, &Glyph_data_type, ptr);
 }
 
-static Glyph *Get_Glyph(VALUE self) {
-    Glyph *ptr;
+static Glyph* Get_Glyph(VALUE self) {
+    Glyph* ptr;
     TypedData_Get_Struct(self, Glyph, &Glyph_data_type, ptr);
     return ptr;
 }
 
+/* call-seq: advance -> Float
+ *
+ * Returns the glyph's horizontal advance.
+ *
+ * @return [Float] the horizontal offset to advance to the next character
+ */
 static VALUE Glyph_get_advance(VALUE self) {
     return DBL2NUM(Get_Glyph(self)->glyph.advance);
 }
 
+/* call-seq: bounds -> Rect
+ *
+ * Returns the glyph's bounding box.
+ *
+ * @return [Rect] the glyph's bounding box, relative to the baseline and
+ *   the cursor position
+ */
 static VALUE Glyph_get_bounds(VALUE self) {
     return rect_to_rb(Get_Glyph(self)->glyph.bounds);
 }
 
+/* call-seq: texture_rect -> Rect
+ *
+ * Returns the sub-rectangle of the texture displayed on the object.
+ *
+ * @return [Rect] the sub-rectangle of the font's texture holding this
+ *   glyph's pixels
+ */
 static VALUE Glyph_get_texture_rect(VALUE self) {
     return int_rect_to_rb(Get_Glyph(self)->glyph.textureRect);
 }
 
-void Init_Glyph(VALUE rb_module) {
-    rb_cGlyph = rb_define_class_under(rb_module, "Glyph", rb_cObject);
+/* Document-class: SFML::Glyph
+ * A single character's rendering metrics and texture location, as returned
+ * by Font#glyph. Read-only.
+ */
+void Init_Glyph(VALUE rb_mSFML) {
+    rb_cGlyph = rb_define_class_under(rb_mSFML, "Glyph", rb_cObject);
 
     rb_define_method(rb_cGlyph, "advance", Glyph_get_advance, 0);
     rb_define_method(rb_cGlyph, "bounds", Glyph_get_bounds, 0);

data/ext/graphics/image.c

@@ -1,6 +1,7 @@
 #include "graphics/image.h"
 
 #include <ruby.h>
+#include <stdint.h>
 #include <stdlib.h>
 
 #include "graphics/color.h"
@@ -13,17 +14,16 @@
 
 static VALUE rb_cImage;
 
-static void Image_free(void *ptr) {
+static void Image_free(void* ptr) {
     sfImage_destroy(ptr);
 }
 
 static const rb_data_type_t Image_data_type = {
     .wrap_struct_name = "SFML::Image",
     .function = {.dmark = NULL, .dfree = Image_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
 
-static VALUE Image_wrap(VALUE klass, sfImage *image) {
+static VALUE Image_wrap(VALUE klass, sfImage* image) {
     if (image == NULL) {
         rb_raise(rb_eRuntimeError, "failed to create image");
     }
@@ -31,67 +31,157 @@ static VALUE Image_wrap(VALUE klass, sfImage *image) {
     return TypedData_Wrap_Struct(klass, &Image_data_type, image);
 }
 
+/* call-seq:
+ *   Image.new(size) -> Image
+ *
+ * Creates a black, fully-opaque image of the given size. +size+ is a
+ * Vector2 or 2-element Array.
+ *
+ * @return [Image]
+ * @raise [RuntimeError] if the image cannot be created
+ */
 static VALUE Image_new(VALUE klass, VALUE rb_size) {
     return Image_wrap(klass, sfImage_create(vec2u_from_rb(rb_size)));
 }
 
+/* call-seq:
+ *   Image.from_color(size, color) -> Image
+ *
+ * Creates an image of the given +size+ filled with +color+.
+ *
+ * @return [Image]
+ * @raise [RuntimeError] if the image cannot be created
+ */
 static VALUE Image_from_color(VALUE klass, VALUE rb_size, VALUE rb_color) {
-    return Image_wrap(klass, sfImage_createFromColor(vec2u_from_rb(rb_size), color_from_rb(rb_color)));
+    return Image_wrap(klass,
+                      sfImage_createFromColor(vec2u_from_rb(rb_size), color_from_rb(rb_color)));
 }
 
+/* call-seq:
+ *   Image.from_pixels(size, pixels) -> Image
+ *
+ * +pixels+ is a String of raw RGBA bytes, at least +width * height * 4+
+ * bytes long.
+ *
+ * @return [Image]
+ * @raise [ArgumentError] if +pixels+ is shorter than required
+ * @raise [RuntimeError] if the image cannot be created
+ */
 static VALUE Image_from_pixels(VALUE klass, VALUE rb_size, VALUE rb_pixels) {
     sfVector2u size = vec2u_from_rb(rb_size);
-    size_t expected = (size_t) size.x * size.y * 4;
-    sfImage *image;
+    size_t expected;
+    sfImage* image;
+
+    /* size.x * size.y * 4 as a bare size_t multiplication can wrap on the
+       32-bit targets this gem ships, e.g. size.x = size.y = 32768: the true
+       product overflows to 0, which would then pass the length check below
+       for any input (even an empty string) and hand CSFML a declared size
+       far larger than the buffer actually backing it. Check before
+       multiplying rather than after. */
+    if (size.x != 0 && size.y > (SIZE_MAX / 4) / size.x) {
+        rb_raise(rb_eArgError, "image dimensions too large");
+    }
+    expected = (size_t)size.x * size.y * 4;
 
     StringValue(rb_pixels);
 
-    if ((size_t) RSTRING_LEN(rb_pixels) < expected) {
-        rb_raise(rb_eArgError, "pixel data too short: expected %lu bytes", (unsigned long) expected);
+    if ((size_t)RSTRING_LEN(rb_pixels) < expected) {
+        rb_raise(rb_eArgError, "pixel data too short: expected %lu bytes", (unsigned long)expected);
     }
 
-    image = sfImage_createFromPixels(size, (const uint8_t *) RSTRING_PTR(rb_pixels));
+    image = sfImage_createFromPixels(size, (const uint8_t*)RSTRING_PTR(rb_pixels));
 
     return Image_wrap(klass, image);
 }
 
+/* call-seq:
+ *   Image.from_file(path) -> Image
+ *
+ * Loads an image from the image file at +filename+.
+ *
+ * @return [Image]
+ * @raise [RuntimeError] if the file cannot be loaded
+ */
 static VALUE Image_from_file(VALUE klass, VALUE rb_path) {
     return Image_wrap(klass, sfImage_createFromFile(StringValueCStr(rb_path)));
 }
 
+/* call-seq:
+ *   Image.from_memory(data) -> Image
+ *
+ * Loads an image from an in-memory image buffer.
+ *
+ * @return [Image]
+ * @raise [RuntimeError] if the image data cannot be decoded
+ */
 static VALUE Image_from_memory(VALUE klass, VALUE rb_data) {
     StringValue(rb_data);
 
-    return Image_wrap(klass, sfImage_createFromMemory(RSTRING_PTR(rb_data), (size_t) RSTRING_LEN(rb_data)));
+    return Image_wrap(klass,
+                      sfImage_createFromMemory(RSTRING_PTR(rb_data), (size_t)RSTRING_LEN(rb_data)));
 }
 
+/* call-seq:
+ *   Image.from_stream(stream) -> Image
+ *
+ * +stream+ is any object responding to the InputStream protocol (see
+ * InputStream).
+ *
+ * @return [Image]
+ * @raise [RuntimeError] if the image cannot be loaded
+ */
 static VALUE Image_from_stream(VALUE klass, VALUE rb_stream) {
     VALUE holder = Qnil;
-    sfInputStream *stream = input_stream_from_rb(rb_stream, &holder);
+    sfInputStream* stream = input_stream_from_rb(rb_stream, &holder);
 
-    (void) holder;
+    (void)holder;
 
     return Image_wrap(klass, sfImage_createFromStream(stream));
 }
 
+/* call-seq: copy -> Image
+ *
+ * Returns a deep copy of the object.
+ *
+ * @return [Image] an independent copy
+ */
 static VALUE Image_copy(VALUE self) {
     return Image_wrap(Get_Klass_Image(), sfImage_copy(Get_Image_Struct(self)));
 }
 
+/* call-seq: size -> Vector2
+ *
+ * Returns the object's size.
+ *
+ * @return [Vector2] the image's dimensions in pixels
+ */
 static VALUE Image_get_size(VALUE self) {
-    return vec2f_to_rb((sfVector2f) {
-        (float) sfImage_getSize(Get_Image_Struct(self)).x,
-        (float) sfImage_getSize(Get_Image_Struct(self)).y
-    });
+    return vec2f_to_rb((sfVector2f){(float)sfImage_getSize(Get_Image_Struct(self)).x,
+                                    (float)sfImage_getSize(Get_Image_Struct(self)).y});
 }
 
+/* call-seq: save_to_file(path) -> true or false
+ *
+ * The format is deduced from +path+'s extension.
+ *
+ * @return [Boolean] whether the save succeeded
+ */
 static VALUE Image_save_to_file(VALUE self, VALUE rb_path) {
     return BOOL2RB(sfImage_saveToFile(Get_Image_Struct(self), StringValueCStr(rb_path)));
 }
 
-static VALUE Image_save_to_memory(int argc, VALUE *argv, VALUE self) {
+/* call-seq:
+ *   save_to_memory(format = "png") -> Buffer or nil
+ *
+ * +format+ is an image file extension without the dot (e.g. +"png"+,
+ * +"bmp"+, +"tga"+, +"jpg"+).
+ *
+ * @return [Buffer, nil] the encoded image data, or +nil+ if encoding failed
+ * @raise [ArgumentError] if given more than one argument
+ */
+static VALUE Image_save_to_memory(int argc, VALUE* argv, VALUE self) {
     VALUE rb_buffer;
-    const char *format = "png";
+    const char* format = "png";
     if (argc > 1) {
         raise_invalid_arguments_excepted(1, argc);
     }
@@ -109,12 +199,28 @@ static VALUE Image_save_to_memory(int argc, VALUE *argv, VALUE self) {
     return Qnil;
 }
 
+/* call-seq: create_mask_from_color(color, alpha) -> self
+ *
+ * Sets the alpha channel of every pixel matching +color+ to +alpha+.
+ *
+ * @return [self]
+ */
 static VALUE Image_create_mask_from_color(VALUE self, VALUE rb_color, VALUE rb_alpha) {
-    sfImage_createMaskFromColor((sfImage *) Get_Image_Struct(self), color_from_rb(rb_color), (uint8_t) NUM2INT(rb_alpha));
+    sfImage_createMaskFromColor((sfImage*)Get_Image_Struct(self), color_from_rb(rb_color),
+                                (uint8_t)NUM2INT(rb_alpha));
     return self;
 }
 
-static VALUE Image_copy_image(int argc, VALUE *argv, VALUE self) {
+/* call-seq:
+ *   copy_image(source, dest, source_rect = Rect.new, apply_alpha = true) -> true or false
+ *
+ * Copies pixels from +source+ (an Image) onto +self+ at position +dest+.
+ * +source_rect+ restricts the copied region; an empty/zero rect copies the
+ * whole source image.
+ *
+ * @return [Boolean] whether the copy succeeded
+ */
+static VALUE Image_copy_image(int argc, VALUE* argv, VALUE self) {
     VALUE rb_source, rb_dest, rb_source_rect, rb_apply_alpha;
     bool apply_alpha = true;
 
@@ -128,47 +234,84 @@ static VALUE Image_copy_image(int argc, VALUE *argv, VALUE self) {
         apply_alpha = RTEST(rb_apply_alpha);
     }
 
-    return BOOL2RB(sfImage_copyImage((sfImage *) Get_Image_Struct(self), Get_Image_Struct(rb_source),
-                                     vec2u_from_rb(rb_dest), int_rect_from_rb(rb_source_rect), apply_alpha));
+    return BOOL2RB(sfImage_copyImage((sfImage*)Get_Image_Struct(self), Get_Image_Struct(rb_source),
+                                     vec2u_from_rb(rb_dest), int_rect_from_rb(rb_source_rect),
+                                     apply_alpha));
 }
 
+/* call-seq: pixel(x, y) -> Color
+ *
+ * Returns the color of the pixel at +x+, +y+.
+ *
+ * @return [Color] the color of the pixel at (+x+, +y+)
+ */
 static VALUE Image_get_pixel(VALUE self, VALUE rb_x, VALUE rb_y) {
-    sfColor color = sfImage_getPixel(Get_Image_Struct(self),
-                                     (sfVector2u) {(unsigned) NUM2UINT(rb_x), (unsigned) NUM2UINT(rb_y)});
+    sfColor color = sfImage_getPixel(
+        Get_Image_Struct(self), (sfVector2u){(unsigned)NUM2UINT(rb_x), (unsigned)NUM2UINT(rb_y)});
 
     return color_to_rb(color);
 }
 
+/* call-seq: set_pixel(x, y, color) -> self
+ *
+ * Sets the color of the pixel at +x+, +y+.
+ *
+ * @return [self]
+ */
 static VALUE Image_set_pixel(VALUE self, VALUE rb_x, VALUE rb_y, VALUE rb_color) {
-    sfImage_setPixel((sfImage *) Get_Image_Struct(self),
-                     (sfVector2u) {(unsigned) NUM2UINT(rb_x), (unsigned) NUM2UINT(rb_y)}, color_from_rb(rb_color));
+    sfImage_setPixel((sfImage*)Get_Image_Struct(self),
+                     (sfVector2u){(unsigned)NUM2UINT(rb_x), (unsigned)NUM2UINT(rb_y)},
+                     color_from_rb(rb_color));
     return self;
 }
 
+/* call-seq: pixels -> String
+ *
+ * Returns a flat array of the image's pixels.
+ *
+ * @return [String] the raw RGBA pixel data, +width * height * 4+ bytes,
+ *   row-major starting from the top-left
+ */
 static VALUE Image_get_pixels(VALUE self) {
-    const sfImage *image = Get_Image_Struct(self);
+    const sfImage* image = Get_Image_Struct(self);
     sfVector2u size = sfImage_getSize(image);
-    const uint8_t *pixels = sfImage_getPixelsPtr(image);
+    const uint8_t* pixels = sfImage_getPixelsPtr(image);
 
     if (pixels == NULL) {
         return rb_str_new("", 0);
     }
 
-    return rb_str_new((const char *) pixels, (long) (size.x * size.y * 4));
+    return rb_str_new((const char*)pixels, (long)(size.x * size.y * 4));
 }
 
+/* call-seq: flip_horizontally! -> self
+ *
+ * Flips the image horizontally.
+ *
+ * @return [self]
+ */
 static VALUE Image_flip_horizontally(VALUE self) {
-    sfImage_flipHorizontally((sfImage *) Get_Image_Struct(self));
+    sfImage_flipHorizontally((sfImage*)Get_Image_Struct(self));
     return self;
 }
 
+/* call-seq: flip_vertically! -> self
+ *
+ * Flips the image vertically.
+ *
+ * @return [self]
+ */
 static VALUE Image_flip_vertically(VALUE self) {
-    sfImage_flipVertically((sfImage *) Get_Image_Struct(self));
+    sfImage_flipVertically((sfImage*)Get_Image_Struct(self));
     return self;
 }
 
-void Init_Image(VALUE rb_module) {
-    rb_cImage = rb_define_class_under(rb_module, "Image", rb_cObject);
+/* Document-class: SFML::Image
+ * A 2D array of RGBA pixels, held in RAM (as opposed to Texture, which is
+ * GPU-side). Used for loading, editing and saving raw pixel data.
+ */
+void Init_Image(VALUE rb_mSFML) {
+    rb_cImage = rb_define_class_under(rb_mSFML, "Image", rb_cObject);
 
     rb_define_singleton_method(rb_cImage, "new", Image_new, 1);
     rb_define_singleton_method(rb_cImage, "from_color", Image_from_color, 2);
@@ -194,12 +337,12 @@ VALUE Get_Klass_Image(void) {
     return rb_cImage;
 }
 
-const sfImage *Get_Image_Struct(VALUE self) {
-    sfImage *ptr;
+const sfImage* Get_Image_Struct(VALUE self) {
+    sfImage* ptr;
     TypedData_Get_Struct(self, sfImage, &Image_data_type, ptr);
     return ptr;
 }
 
-VALUE image_from_c(sfImage *image) {
+VALUE image_from_c(sfImage* image) {
     return Image_wrap(Get_Klass_Image(), image);
 }