sfml3-rb 0.2.2 → 0.3.1

data/ext/window/keyboard.c

@@ -11,125 +11,125 @@
 /* Indexed by sfKeyCode rather than by position: if upstream reorders or
    removes a key, this fails to compile instead of silently renaming every
    key after the change. sfKeyUnknown is -1 and so has no entry. */
-static const char *keys[] = {
-        [sfKeyA] = "a",
-        [sfKeyB] = "b",
-        [sfKeyC] = "c",
-        [sfKeyD] = "d",
-        [sfKeyE] = "e",
-        [sfKeyF] = "f",
-        [sfKeyG] = "g",
-        [sfKeyH] = "h",
-        [sfKeyI] = "i",
-        [sfKeyJ] = "j",
-        [sfKeyK] = "k",
-        [sfKeyL] = "l",
-        [sfKeyM] = "m",
-        [sfKeyN] = "n",
-        [sfKeyO] = "o",
-        [sfKeyP] = "p",
-        [sfKeyQ] = "q",
-        [sfKeyR] = "r",
-        [sfKeyS] = "s",
-        [sfKeyT] = "t",
-        [sfKeyU] = "u",
-        [sfKeyV] = "v",
-        [sfKeyW] = "w",
-        [sfKeyX] = "x",
-        [sfKeyY] = "y",
-        [sfKeyZ] = "z",
-        [sfKeyNum0] = "num0",
-        [sfKeyNum1] = "num1",
-        [sfKeyNum2] = "num2",
-        [sfKeyNum3] = "num3",
-        [sfKeyNum4] = "num4",
-        [sfKeyNum5] = "num5",
-        [sfKeyNum6] = "num6",
-        [sfKeyNum7] = "num7",
-        [sfKeyNum8] = "num8",
-        [sfKeyNum9] = "num9",
-        [sfKeyEscape] = "escape",
-        [sfKeyLControl] = "LControl",
-        [sfKeyLShift] = "LShift",
-        [sfKeyLAlt] = "LAlt",
-        [sfKeyLSystem] = "LSystem",
-        [sfKeyRControl] = "RControl",
-        [sfKeyRShift] = "RShift",
-        [sfKeyRAlt] = "RAlt",
-        [sfKeyRSystem] = "RSystem",
-        [sfKeyMenu] = "Menu",
-        [sfKeyLBracket] = "LBracket",
-        [sfKeyRBracket] = "RBracket",
-        [sfKeySemicolon] = "Semicolon",
-        [sfKeyComma] = "Comma",
-        [sfKeyPeriod] = "Period",
-        [sfKeyApostrophe] = "Quote",
-        [sfKeySlash] = "Slash",
-        [sfKeyBackslash] = "Backslash",
-        [sfKeyGrave] = "Tilde",
-        [sfKeyEqual] = "Equal",
-        [sfKeyHyphen] = "Hyphen",
-        [sfKeySpace] = "Space",
-        [sfKeyEnter] = "Enter",
-        [sfKeyBackspace] = "Backspace",
-        [sfKeyTab] = "Tab",
-        [sfKeyPageUp] = "PageUp",
-        [sfKeyPageDown] = "PageDown",
-        [sfKeyEnd] = "End",
-        [sfKeyHome] = "Home",
-        [sfKeyInsert] = "Insert",
-        [sfKeyDelete] = "Delete",
-        [sfKeyAdd] = "Add",
-        [sfKeySubtract] = "Subtract",
-        [sfKeyMultiply] = "Multiply",
-        [sfKeyDivide] = "Divide",
-        [sfKeyLeft] = "Left",
-        [sfKeyRight] = "Right",
-        [sfKeyUp] = "Up",
-        [sfKeyDown] = "Down",
-        [sfKeyNumpad0] = "Numpad0",
-        [sfKeyNumpad1] = "Numpad1",
-        [sfKeyNumpad2] = "Numpad2",
-        [sfKeyNumpad3] = "Numpad3",
-        [sfKeyNumpad4] = "Numpad4",
-        [sfKeyNumpad5] = "Numpad5",
-        [sfKeyNumpad6] = "Numpad6",
-        [sfKeyNumpad7] = "Numpad7",
-        [sfKeyNumpad8] = "Numpad8",
-        [sfKeyNumpad9] = "Numpad9",
-        [sfKeyF1] = "f1",
-        [sfKeyF2] = "f2",
-        [sfKeyF3] = "f3",
-        [sfKeyF4] = "f4",
-        [sfKeyF5] = "f5",
-        [sfKeyF6] = "f6",
-        [sfKeyF7] = "f7",
-        [sfKeyF8] = "f8",
-        [sfKeyF9] = "f9",
-        [sfKeyF10] = "f10",
-        [sfKeyF11] = "f11",
-        [sfKeyF12] = "f12",
-        [sfKeyF13] = "f13",
-        [sfKeyF14] = "f14",
-        [sfKeyF15] = "f15",
-        [sfKeyPause] = "pause",
+static const char* keys[] = {
+    [sfKeyA] = "a",
+    [sfKeyB] = "b",
+    [sfKeyC] = "c",
+    [sfKeyD] = "d",
+    [sfKeyE] = "e",
+    [sfKeyF] = "f",
+    [sfKeyG] = "g",
+    [sfKeyH] = "h",
+    [sfKeyI] = "i",
+    [sfKeyJ] = "j",
+    [sfKeyK] = "k",
+    [sfKeyL] = "l",
+    [sfKeyM] = "m",
+    [sfKeyN] = "n",
+    [sfKeyO] = "o",
+    [sfKeyP] = "p",
+    [sfKeyQ] = "q",
+    [sfKeyR] = "r",
+    [sfKeyS] = "s",
+    [sfKeyT] = "t",
+    [sfKeyU] = "u",
+    [sfKeyV] = "v",
+    [sfKeyW] = "w",
+    [sfKeyX] = "x",
+    [sfKeyY] = "y",
+    [sfKeyZ] = "z",
+    [sfKeyNum0] = "num0",
+    [sfKeyNum1] = "num1",
+    [sfKeyNum2] = "num2",
+    [sfKeyNum3] = "num3",
+    [sfKeyNum4] = "num4",
+    [sfKeyNum5] = "num5",
+    [sfKeyNum6] = "num6",
+    [sfKeyNum7] = "num7",
+    [sfKeyNum8] = "num8",
+    [sfKeyNum9] = "num9",
+    [sfKeyEscape] = "escape",
+    [sfKeyLControl] = "LControl",
+    [sfKeyLShift] = "LShift",
+    [sfKeyLAlt] = "LAlt",
+    [sfKeyLSystem] = "LSystem",
+    [sfKeyRControl] = "RControl",
+    [sfKeyRShift] = "RShift",
+    [sfKeyRAlt] = "RAlt",
+    [sfKeyRSystem] = "RSystem",
+    [sfKeyMenu] = "Menu",
+    [sfKeyLBracket] = "LBracket",
+    [sfKeyRBracket] = "RBracket",
+    [sfKeySemicolon] = "Semicolon",
+    [sfKeyComma] = "Comma",
+    [sfKeyPeriod] = "Period",
+    [sfKeyApostrophe] = "Quote",
+    [sfKeySlash] = "Slash",
+    [sfKeyBackslash] = "Backslash",
+    [sfKeyGrave] = "Tilde",
+    [sfKeyEqual] = "Equal",
+    [sfKeyHyphen] = "Hyphen",
+    [sfKeySpace] = "Space",
+    [sfKeyEnter] = "Enter",
+    [sfKeyBackspace] = "Backspace",
+    [sfKeyTab] = "Tab",
+    [sfKeyPageUp] = "PageUp",
+    [sfKeyPageDown] = "PageDown",
+    [sfKeyEnd] = "End",
+    [sfKeyHome] = "Home",
+    [sfKeyInsert] = "Insert",
+    [sfKeyDelete] = "Delete",
+    [sfKeyAdd] = "Add",
+    [sfKeySubtract] = "Subtract",
+    [sfKeyMultiply] = "Multiply",
+    [sfKeyDivide] = "Divide",
+    [sfKeyLeft] = "Left",
+    [sfKeyRight] = "Right",
+    [sfKeyUp] = "Up",
+    [sfKeyDown] = "Down",
+    [sfKeyNumpad0] = "Numpad0",
+    [sfKeyNumpad1] = "Numpad1",
+    [sfKeyNumpad2] = "Numpad2",
+    [sfKeyNumpad3] = "Numpad3",
+    [sfKeyNumpad4] = "Numpad4",
+    [sfKeyNumpad5] = "Numpad5",
+    [sfKeyNumpad6] = "Numpad6",
+    [sfKeyNumpad7] = "Numpad7",
+    [sfKeyNumpad8] = "Numpad8",
+    [sfKeyNumpad9] = "Numpad9",
+    [sfKeyF1] = "f1",
+    [sfKeyF2] = "f2",
+    [sfKeyF3] = "f3",
+    [sfKeyF4] = "f4",
+    [sfKeyF5] = "f5",
+    [sfKeyF6] = "f6",
+    [sfKeyF7] = "f7",
+    [sfKeyF8] = "f8",
+    [sfKeyF9] = "f9",
+    [sfKeyF10] = "f10",
+    [sfKeyF11] = "f11",
+    [sfKeyF12] = "f12",
+    [sfKeyF13] = "f13",
+    [sfKeyF14] = "f14",
+    [sfKeyF15] = "f15",
+    [sfKeyPause] = "pause",
 };
 
 #define LENGTH_KEYS (sizeof(keys) / sizeof(keys[0]))
 
-int find_key(const char *name) {
+int find_key(const char* name) {
     size_t i;
 
     for (i = 0; i < LENGTH_KEYS; i++) {
         if (keys[i] != NULL && strcmp(keys[i], name) == 0) {
-            return (int) i;
+            return (int)i;
         }
     }
 
     return -1;
 }
 
-const char *get_key_event(unsigned int key) {
+const char* get_key_event(unsigned int key) {
     if (key < LENGTH_KEYS && keys[key] != NULL) {
         return keys[key];
     }
@@ -141,7 +141,7 @@ static int Keyboard_key_code(VALUE rb_key) {
     int code;
 
     if (SYMBOL_P(rb_key)) {
-        const char *name = rb_id2name(SYM2ID(rb_key));
+        const char* name = rb_id2name(SYM2ID(rb_key));
 
         code = find_key(name);
 
@@ -153,7 +153,7 @@ static int Keyboard_key_code(VALUE rb_key) {
     }
 
     if (RB_TYPE_P(rb_key, T_STRING)) {
-        const char *name = StringValueCStr(rb_key);
+        const char* name = StringValueCStr(rb_key);
 
         code = find_key(name);
 
@@ -167,41 +167,93 @@ static int Keyboard_key_code(VALUE rb_key) {
     return NUM2INT(rb_key);
 }
 
+/* call-seq:
+ *   pressed?(key) -> true or false
+ *
+ * +key+ may be a key Symbol (e.g. +:a+, +:Enter+, +:LShift+), a String key
+ * name, or an Integer key code.
+ *
+ * @return [Boolean]
+ * @raise [ArgumentError] if +key+ is a Symbol/String naming an unknown key
+ */
 static VALUE Keyboard_pressed_p(VALUE module, VALUE rb_key) {
-    return BOOL2RB(sfKeyboard_isKeyPressed((sfKeyCode) Keyboard_key_code(rb_key)));
+    return BOOL2RB(sfKeyboard_isKeyPressed((sfKeyCode)Keyboard_key_code(rb_key)));
 }
 
+/* call-seq:
+ *   scancode_pressed?(scancode) -> true or false
+ *
+ * Unlike #pressed?, +scancode+ identifies a physical key position rather
+ * than the character it currently produces.
+ *
+ * @return [Boolean]
+ */
 static VALUE Keyboard_scancode_pressed_p(VALUE module, VALUE rb_scancode) {
-    return BOOL2RB(sfKeyboard_isScancodePressed((sfScancode) NUM2INT(rb_scancode)));
+    return BOOL2RB(sfKeyboard_isScancodePressed((sfScancode)NUM2INT(rb_scancode)));
 }
 
+/* call-seq:
+ *   localize(scancode) -> Symbol
+ *
+ * Returns the key Symbol that +scancode+ produces on the current layout.
+ *
+ * @return [Symbol] the key that +scancode+ produces on the current keyboard
+ *   layout
+ */
 static VALUE Keyboard_localize(VALUE module, VALUE rb_scancode) {
-    return ID2SYM(rb_intern(get_key_event((unsigned int) sfKeyboard_localize((sfScancode) NUM2INT(rb_scancode)))));
+    return ID2SYM(rb_intern(
+        get_key_event((unsigned int)sfKeyboard_localize((sfScancode)NUM2INT(rb_scancode)))));
 }
 
+/* call-seq:
+ *   delocalize(key) -> Integer
+ *
+ * Returns the scancode that produces +key+ on the current keyboard layout.
+ *
+ * @return [Integer] the scancode that produces +key+ on the current keyboard
+ *   layout
+ * @raise [ArgumentError] if +key+ is a Symbol/String naming an unknown key
+ */
 static VALUE Keyboard_delocalize(VALUE module, VALUE rb_key) {
-    return INT2NUM(sfKeyboard_delocalize((sfKeyCode) Keyboard_key_code(rb_key)));
+    return INT2NUM(sfKeyboard_delocalize((sfKeyCode)Keyboard_key_code(rb_key)));
 }
 
+/* call-seq:
+ *   description(scancode) -> String
+ *
+ * Returns a human-readable, localized name for +scancode+.
+ *
+ * @return [String] a human-readable, localized name for +scancode+
+ */
 static VALUE Keyboard_description(VALUE module, VALUE rb_scancode) {
-    const char *description = sfKeyboard_getDescription((sfScancode) NUM2INT(rb_scancode));
+    const char* description = sfKeyboard_getDescription((sfScancode)NUM2INT(rb_scancode));
 
     return rb_str_new_cstr(description != NULL ? description : "");
 }
 
+/* call-seq:
+ *   virtual_keyboard_visible=(value) -> true or false
+ *
+ * Shows or hides the on-screen keyboard, where the platform provides one.
+ *
+ * @return [Boolean] +value+
+ */
 static VALUE Keyboard_set_virtual_keyboard_visible(VALUE module, VALUE rb_visible) {
     sfKeyboard_setVirtualKeyboardVisible(RTEST(rb_visible));
     return rb_visible;
 }
 
-void Init_Keyboard(VALUE rb_module) {
-    VALUE rb_mKeyboard = rb_define_module_under(rb_module, "Keyboard");
+/* Document-module: SFML::Keyboard
+ * Real-time keyboard state and key/scancode lookups.
+ */
+void Init_Keyboard(VALUE rb_mSFML) {
+    VALUE rb_mKeyboard = rb_define_module_under(rb_mSFML, "Keyboard");
 
     rb_define_module_function(rb_mKeyboard, "pressed?", Keyboard_pressed_p, 1);
     rb_define_module_function(rb_mKeyboard, "scancode_pressed?", Keyboard_scancode_pressed_p, 1);
     rb_define_module_function(rb_mKeyboard, "localize", Keyboard_localize, 1);
     rb_define_module_function(rb_mKeyboard, "delocalize", Keyboard_delocalize, 1);
     rb_define_module_function(rb_mKeyboard, "description", Keyboard_description, 1);
-    rb_define_module_function(rb_mKeyboard, "virtual_keyboard_visible=",
-                              Keyboard_set_virtual_keyboard_visible, 1);
+    rb_define_module_function(
+        rb_mKeyboard, "virtual_keyboard_visible=", Keyboard_set_virtual_keyboard_visible, 1);
 }

data/ext/window/mouse.c

@@ -4,29 +4,63 @@
 
 #include "window/input_enums.h"
 #include "window/window.h"
+#include "window/window_base.h"
 #include "system/vec2.h"
 #include "core/exceptions.h"
 #include "core/macros.h"
 #include "core/sfml.h"
 
-/* nil means desktop-relative. CSFML gives sfRenderWindow its own entry points,
-   so a window argument never has to be cast down to sfWindowBase. */
-static const sfRenderWindow* Mouse_relative_window(VALUE rb_window) {
-    if (NIL_P(rb_window)) {
-        return NULL;
+/* A RenderWindow and a Window both wrap an sfRenderWindow; a WindowBase wraps
+   an sfWindowBase. CSFML ships a separate entry point for each, so pick the one
+   matching the handle -- casting an sfRenderWindow* down to sfWindowBase* would
+   rely on the base being at offset 0, which CSFML does not guarantee. */
+static sfVector2i Mouse_get_relative_position(VALUE rb_window) {
+    if (rb_obj_is_kind_of(rb_window, Get_Klass_Window())) {
+        return sfMouse_getPositionRenderWindow(Get_Window_Struct(rb_window));
+    }
+
+    if (rb_obj_is_kind_of(rb_window, Get_Klass_WindowBase())) {
+        return sfMouse_getPositionWindowBase(Get_WindowBase_Struct(rb_window));
+    }
+
+    raise_invalid_argument_class(Get_Klass_WindowBase());
+    return (sfVector2i){0, 0};
+}
+
+static void Mouse_set_relative_position(VALUE rb_window, sfVector2i position) {
+    if (rb_obj_is_kind_of(rb_window, Get_Klass_Window())) {
+        sfMouse_setPositionRenderWindow(position, Get_Window_Struct(rb_window));
+        return;
     }
 
-    if (!rb_obj_is_kind_of(rb_window, Get_Klass_Window())) {
-        raise_invalid_argument_class(Get_Klass_Window());
+    if (rb_obj_is_kind_of(rb_window, Get_Klass_WindowBase())) {
+        sfMouse_setPositionWindowBase(position, Get_WindowBase_Struct(rb_window));
+        return;
     }
 
-    return Get_Window_Struct(rb_window);
+    raise_invalid_argument_class(Get_Klass_WindowBase());
 }
 
+/* call-seq:
+ *   button_pressed?(button) -> true or false
+ *
+ * Returns +true+ if +button+ is currently pressed.
+ *
+ * @return [Boolean] whether +button+ (a Symbol like +:left+, +:right+,
+ *   +:middle+, or an Integer) is currently pressed
+ */
 static VALUE Mouse_is_button_pressed(VALUE module, VALUE rb_button) {
     return BOOL2RB(sfMouse_isButtonPressed(mouse_button_from_rb(rb_button)));
 }
 
+/* call-seq:
+ *   position(window = nil) -> Vector2
+ *
+ * Returns the mouse position in desktop coordinates, or relative to +window+.
+ *
+ * @return [Vector2] the mouse position in desktop coordinates, or relative
+ *   to +window+'s client area when given
+ */
 static VALUE Mouse_get_position(int argc, VALUE* argv, VALUE module) {
     VALUE rb_window;
     sfVector2i position;
@@ -35,12 +69,20 @@ static VALUE Mouse_get_position(int argc, VALUE* argv, VALUE module) {
     if (NIL_P(rb_window)) {
         position = sfMouse_getPosition(NULL);
     } else {
-        position = sfMouse_getPositionRenderWindow(Mouse_relative_window(rb_window));
+        position = Mouse_get_relative_position(rb_window);
     }
 
     return vec2f_to_rb((sfVector2f){(float)position.x, (float)position.y});
 }
 
+/* call-seq:
+ *   set_position(position, window = nil) -> position
+ *
+ * Moves the mouse cursor to +position+, in desktop coordinates, or relative
+ * to +window+'s client area when given.
+ *
+ * @return [Vector2] +position+
+ */
 static VALUE Mouse_set_position(int argc, VALUE* argv, VALUE module) {
     VALUE rb_position, rb_window;
 
@@ -48,19 +90,28 @@ static VALUE Mouse_set_position(int argc, VALUE* argv, VALUE module) {
     if (NIL_P(rb_window)) {
         sfMouse_setPosition(vec2i_from_rb(rb_position), NULL);
     } else {
-        sfMouse_setPositionRenderWindow(vec2i_from_rb(rb_position),
-                                        Mouse_relative_window(rb_window));
+        Mouse_set_relative_position(rb_window, vec2i_from_rb(rb_position));
     }
 
     return rb_position;
 }
 
+/* call-seq:
+ *   position=(value) -> value
+ *
+ * Moves the mouse cursor to +value+, in desktop coordinates.
+ *
+ * @return [Vector2] +value+
+ */
 static VALUE Mouse_position_eq(VALUE module, VALUE rb_position) {
     return Mouse_set_position(1, &rb_position, module);
 }
 
-void Init_Mouse(VALUE rb_module) {
-    VALUE rb_mMouse = rb_define_module_under(rb_module, "Mouse");
+/* Document-module: SFML::Mouse
+ * Real-time mouse state and cursor positioning.
+ */
+void Init_Mouse(VALUE rb_mSFML) {
+    VALUE rb_mMouse = rb_define_module_under(rb_mSFML, "Mouse");
 
     rb_define_module_function(rb_mMouse, "button_pressed?", Mouse_is_button_pressed, 1);
     rb_define_module_function(rb_mMouse, "pressed?", Mouse_is_button_pressed, 1);

data/ext/window/sensor.c

@@ -7,21 +7,47 @@
 #include "core/macros.h"
 #include "core/sfml.h"
 
+/* call-seq:
+ *   available?(type) -> true or false
+ *
+ * Returns +true+ if sensor +type+ is available on this device.
+ *
+ * @return [Boolean] whether sensor +type+ (a Symbol like
+ *   +:accelerometer+, +:gyroscope+) is available on this device
+ */
 static VALUE Sensor_is_available(VALUE module, VALUE rb_type) {
     return BOOL2RB(sfSensor_isAvailable(sensor_type_from_rb(rb_type)));
 }
 
+/* call-seq:
+ *   set_enabled(type, value) -> value
+ *
+ * Enables or disables sensor +type+. All sensors are disabled by default.
+ *
+ * @return [Boolean] +value+
+ */
 static VALUE Sensor_set_enabled(VALUE module, VALUE rb_type, VALUE rb_enabled) {
     sfSensor_setEnabled(sensor_type_from_rb(rb_type), RTEST(rb_enabled));
     return rb_enabled;
 }
 
+/* call-seq:
+ *   value(type) -> Vector3
+ *
+ * Returns the current value of sensor +type+.
+ *
+ * @return [Vector3] the current value of sensor +type+
+ */
 static VALUE Sensor_get_value(VALUE module, VALUE rb_type) {
     return vec3f_to_rb(sfSensor_getValue(sensor_type_from_rb(rb_type)));
 }
 
-void Init_Sensor(VALUE rb_module) {
-    VALUE rb_mSensor = rb_define_module_under(rb_module, "Sensor");
+/* Document-module: SFML::Sensor
+ * Access to hardware sensors (accelerometer, gyroscope, etc.), mainly
+ * relevant on mobile platforms.
+ */
+void Init_Sensor(VALUE rb_mSFML) {
+    VALUE rb_mSensor = rb_define_module_under(rb_mSFML, "Sensor");
 
     rb_define_module_function(rb_mSensor, "available?", Sensor_is_available, 1);
     rb_define_module_function(rb_mSensor, "set_enabled", Sensor_set_enabled, 2);

data/ext/window/touch.c

@@ -3,29 +3,47 @@
 #include <ruby.h>
 
 #include "window/window.h"
+#include "window/window_base.h"
 #include "system/vec2.h"
 #include "core/exceptions.h"
 #include "core/macros.h"
 #include "core/sfml.h"
 
-/* nil means desktop-relative. CSFML gives sfRenderWindow its own entry point,
-   so a window argument never has to be cast down to sfWindowBase. */
-static const sfRenderWindow* Touch_relative_window(VALUE rb_window) {
-    if (NIL_P(rb_window)) {
-        return NULL;
+/* A RenderWindow and a Window both wrap an sfRenderWindow; a WindowBase wraps
+   an sfWindowBase. CSFML ships a separate entry point for each, so pick the one
+   matching the handle rather than casting between them. */
+static sfVector2i Touch_relative_position(unsigned int finger, VALUE rb_window) {
+    if (rb_obj_is_kind_of(rb_window, Get_Klass_Window())) {
+        return sfTouch_getPositionRenderWindow(finger, Get_Window_Struct(rb_window));
     }
 
-    if (!rb_obj_is_kind_of(rb_window, Get_Klass_Window())) {
-        raise_invalid_argument_class(Get_Klass_Window());
+    if (rb_obj_is_kind_of(rb_window, Get_Klass_WindowBase())) {
+        return sfTouch_getPositionWindowBase(finger, Get_WindowBase_Struct(rb_window));
     }
 
-    return Get_Window_Struct(rb_window);
+    raise_invalid_argument_class(Get_Klass_WindowBase());
+    return (sfVector2i){0, 0};
 }
 
+/* call-seq:
+ *   down?(finger) -> true or false
+ *
+ * Returns +true+ if touch point +finger+ is currently down.
+ *
+ * @return [Boolean] whether touch point +finger+ is currently down
+ */
 static VALUE Touch_is_down(VALUE module, VALUE rb_finger) {
     return BOOL2RB(sfTouch_isDown(NUM2UINT(rb_finger)));
 }
 
+/* call-seq:
+ *   position(finger, window = nil) -> Vector2
+ *
+ * Returns the position of touch point +finger+.
+ *
+ * @return [Vector2] the position of touch point +finger+, in desktop
+ *   coordinates, or relative to +window+'s client area when given
+ */
 static VALUE Touch_get_position(int argc, VALUE* argv, VALUE module) {
     VALUE rb_finger, rb_window;
     sfVector2i position;
@@ -34,15 +52,17 @@ static VALUE Touch_get_position(int argc, VALUE* argv, VALUE module) {
     if (NIL_P(rb_window)) {
         position = sfTouch_getPosition(NUM2UINT(rb_finger), NULL);
     } else {
-        position =
-            sfTouch_getPositionRenderWindow(NUM2UINT(rb_finger), Touch_relative_window(rb_window));
+        position = Touch_relative_position(NUM2UINT(rb_finger), rb_window);
     }
 
     return vec2f_to_rb((sfVector2f){(float)position.x, (float)position.y});
 }
 
-void Init_Touch(VALUE rb_module) {
-    VALUE rb_mTouch = rb_define_module_under(rb_module, "Touch");
+/* Document-module: SFML::Touch
+ * Real-time touch-screen state.
+ */
+void Init_Touch(VALUE rb_mSFML) {
+    VALUE rb_mTouch = rb_define_module_under(rb_mSFML, "Touch");
 
     rb_define_module_function(rb_mTouch, "down?", Touch_is_down, 1);
     rb_define_module_function(rb_mTouch, "position", Touch_get_position, -1);