sfml3-rb 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc41a984a71094455d29e95d4c529a1e228e5c5442333aca6eb57b9b7c9d3f5e
-  data.tar.gz: 835286043ece71ba5dc8c1790cdd6ab0370ae0924823771e03a811cd8acba1af
+  metadata.gz: 2ef7284361fdd31619f9f97c920664262125cfb26936bbc8a6425ff6c585e12c
+  data.tar.gz: 59baa039d3fa9f7d704469f3204070dc90dc8db48f2be3e9737c7e888554ed7e
 SHA512:
-  metadata.gz: f75f7ce8244a36a0a8e93903ea0d323513753cfdf3e82f79364b3081a3d5ac651609897a0d4911c2509aac1e5107c37ab9ea9341eede85bb630a05228273ed3d
-  data.tar.gz: 68a989c7d4e1147cd5585bf8db85be15c3c1419bbefaeca95791fa37575900d8b841d1b33dd5009f9611e3b5a365b7410c7687ca8eecf96d188a05feb6de269f
+  metadata.gz: d2d1dbf0f61b9c418e1aa01e81770158390cb28b9f297157195357463bd7ac6ca2e8ac0d2974f295968f4e762dd6e4affa330bf72df4cba5588a4bc30f459c74
+  data.tar.gz: 2b959e3a75e33a5633ec3cdaf64e2d5c95bdaa62ff58d37e981b114a3e52b0a69df5594c1adbf32a47446c3c1d4bd3f961a99ae06f56dde83ce80af2b6468934

data/.yardopts

@@ -0,0 +1,9 @@
+--markup markdown
+--output-dir doc
+--title sfml3-rb
+--readme README.md
+ext/**/*.c
+-
+CHANGELOG.md
+TODO.md
+LICENSE.md

data/CHANGELOG.md

@@ -6,26 +6,52 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
-### Added
-* **Full YARD API documentation and RBS type signatures**, covering every
-  bound class, module, method and constant. Doc comments live in-place in
-  the `ext/**/*.c` sources (YARD's C parser, the same convention RDoc uses),
-  so they're published automatically to
-  [rubydoc.info](https://rubydoc.info/gems/sfml3-rb) on release; `rake yard`
-  builds them locally into `doc/`. `sig/**/*.rbs` ships in the gem alongside
-  the extension sources, for IDE completion (Solargraph, RubyMine) and
-  static type-checking (Sorbet, Steep). Run `rake rbs` to validate the
-  signatures.
+## [0.3.0] - 2026-09-19
 
-## [0.2.2]
+### Added
+* **Four more experimental binary-gem targets**: `aarch64-linux-musl`, `arm-linux-gnu`
+  (ARMv7 hard-float), `arm-linux-musl`, and `aarch64-mingw-ucrt` (64-bit Windows on ARM).
+  All four ride the same rake-compiler-dock cross-compilation this project already uses for
+  its other targets; none has been run on its target hardware yet, so all are
+  `experimental` in `publish.yaml` like `aarch64-linux-gnu`, `x86_64-darwin` and
+  `arm64-darwin` already were. `script/provision.sh` gained matching cases for the two new
+  glibc/musl Linux targets.
+* `rakelib/package.rake`'s `EXPECTED_ABIS` gained an entry for `aarch64-mingw-ucrt`: its
+  rake-compiler-dock image carries no cross Ruby older than 3.4, so that gem has no floor
+  below it — the same kind of upstream gap `x86-mingw32` already has at the top end.
+* `aarch64-linux-gnu` is now additionally run — not just cross-compiled — by a new
+  `test-arm64.yaml` workflow, on GitHub's hosted `ubuntu-24.04-arm` runner. It stays
+  `experimental` in `publish.yaml` for now; this is the evidence that will eventually
+  justify dropping that flag.
+* ARMv6 (32-bit), RISC-V (rv64gc), PowerPC (ppc64le), and any BSD are deliberately not
+  covered by a binary gem: rake-compiler-dock ships no cross-compilation image for any of
+  them, and building custom cross-toolchain infrastructure for them is a much larger,
+  separate undertaking. The source-gem fallback remains the only path there, unchanged.
 
 ### Fixed
-* **The macOS binary gems now build.** SFML 3.0.2 defaults
-  `CMAKE_OSX_DEPLOYMENT_TARGET` to 13.0, but the osxcross SDK in the
-  rake-compiler-dock image is 11.1 and rejects a newer target, so both Darwin
-  builds aborted while configuring SFML. The ports toolchain now pins the
-  deployment target to macOS 11.0, which is the floor Apple Silicon requires
-  anyway.
+* **A GC race in the audio bindings aborted the process on arm64.** `Sound`, `Music` and
+  `SoundStream` released the GVL inside their `dfree`, but their data types were marked
+  `RUBY_TYPED_FREE_IMMEDIATELY`, so the free could run *during* garbage collection: another
+  thread (Ruby's `Timeout` thread, in the test suite) could then allocate while GC was mid-cycle
+  and Ruby aborted with "object allocation during garbage collection phase". Dropping the flag
+  defers the free to a safe point; releasing the GVL is still what keeps `sf*_destroy` from
+  deadlocking against the audio thread.
+
+### Documentation
+* **Every public class, module, method and constant is documented**, with the
+  result rendered on [rubydoc.info](https://rubydoc.info/gems/sfml3-rb). The
+  comments live beside each binding in `ext/**/*.c`; `rake yard` builds them
+  into `doc/`. Previously the comments carried `call-seq` and `@return` tags
+  but little prose, so rubydoc.info showed a signature with a blank
+  description; every such method now has a sentence of its own.
+* RBS type signatures for the same surface ship in `sig/**/*.rbs`, for IDE
+  completion (Solargraph, RubyMine) and static checking (Sorbet, Steep);
+  `rake rbs` validates them.
+* `.yardopts` ships in the gem, so rubydoc.info generates with the same title,
+  README and extra files as `rake yard`.
+* `rake doc:undoc` fails when a method is left without a description, so the
+  coverage cannot regress silently (`yard stats` uses `blank?` and passes for
+  tag-only comments, which is how the blanks went unnoticed).
 
 ## [0.2.1]
 

data/README.md

@@ -2,17 +2,40 @@
 
 Ruby bindings for [SFML 3](https://www.sfml-dev.org/), via its C API, [CSFML](https://github.com/SFML/CSFML).
 
-## Status
-
-Latest release: **0.2.2**. Bound against **CSFML 3**. See [TODO.md](TODO.md) for which parts of the
-SFML 3 API are ported so far, and [CHANGELOG.md](CHANGELOG.md) for what changed recently.
-
-API docs (every class, module, method and constant) are on
-[rubydoc.info](https://rubydoc.info/gems/sfml3-rb). The gem also ships RBS type signatures
-(`sig/**/*.rbs`) alongside the extension sources, for IDE completion (Solargraph, RubyMine) and
-static type-checking (Sorbet, Steep).
-
-## Install
+[![Ruby](https://img.shields.io/badge/ruby-3.1%2B-red?style=flat-square)](https://www.ruby-lang.org/)
+[![Test](https://github.com/algaves/sfml3.rb/actions/workflows/test.yaml/badge.svg)](https://github.com/algaves/sfml3.rb/actions/workflows/test.yaml)
+[![Check](https://github.com/algaves/sfml3.rb/actions/workflows/check.yaml/badge.svg)](https://github.com/algaves/sfml3.rb/actions/workflows/check.yaml)
+[![Gem Version](https://img.shields.io/gem/v/sfml3-rb?style=flat-square)](https://rubygems.org/gems/sfml3-rb)
+[![Gem Downloads](https://img.shields.io/gem/dt/sfml3-rb?style=flat-square)](https://rubygems.org/gems/sfml3-rb)
+[![License](https://img.shields.io/badge/license-0BSD-green?style=flat-square)](LICENSE.md)
+
+Latest release: **0.3.0**, bound against **CSFML 3**.
+
+## Features
+
+* **Broad coverage of SFML 3**, bound through CSFML: windows and events, graphics, audio, network,
+  and the system layer, with every `sf*` entry point tracked in [TODO.md](TODO.md).
+* **Precompiled binary gems** for common platforms, with FreeType, SFML 3 and CSFML 3 statically
+  linked in — no toolchain and nothing to install system-wide.
+* **A source fallback everywhere else**, which downloads and builds the pinned, checksum-verified
+  dependencies at install time, so the gem works on macOS, ARM and the BSDs out of the box.
+* **Complete API documentation and types**: every class, module, method and constant is documented
+  on [rubydoc.info](https://rubydoc.info/gems/sfml3-rb) and covered by RBS signatures shipped in
+  the gem.
+* **A close fit to SFML's own model**: classes mirror the C++ types (Window, Texture, Sprite,
+  Sound, ...) minus the parts that only exist in C++, like `std::string` and exceptions.
+
+## Table of Contents
+
+* [Installation](#installation)
+* [Quick Start](#quick-start)
+* [Documentation](#documentation)
+* [Development](#development)
+* [Contributing](#contributing)
+* [Acknowledgements](#acknowledgements)
+* [License](#license)
+
+## Installation
 
 ```sh
 gem install sfml3-rb
@@ -29,11 +52,18 @@ already linked in — no toolchain, no build, nothing to install system-wide:
 | `x86-linux-musl` | 3.1 – 4.0 | 32-bit musl |
 | `x64-mingw-ucrt` | 3.1 – 4.0 | 64-bit Windows, RubyInstaller 3.1+ |
 | `x86-mingw32` | 3.1 – **3.4** | 32-bit Windows |
-| `aarch64-linux-gnu`, `x86_64-darwin`, `arm64-darwin` | 3.1 – 4.0 | experimental, not yet built |
+| `aarch64-linux-gnu` | 3.1 – 4.0 | experimental, cross-built and run on a native arm64 CI runner |
+| `aarch64-linux-musl`, `arm-linux-gnu`, `arm-linux-musl` | 3.1 – 4.0 | experimental, not yet built |
+| `aarch64-mingw-ucrt` | 3.4 – **4.0** | experimental, 64-bit Windows on ARM |
+| `x86_64-darwin`, `arm64-darwin` | 3.1 – 4.0 | experimental, not yet built |
 
-Each gem carries one extension per Ruby ABI. Two gaps come from upstream rather than from this
-project: **RubyInstaller publishes no 32-bit Ruby 4.0**, so `x86-mingw32` stops at 3.4; and 64-bit
-Windows before Ruby 3.1 used a different platform (`x64-mingw32`), which is not built.
+Each gem carries one extension per Ruby ABI. Three gaps come from upstream rather than from this
+project: **RubyInstaller publishes no 32-bit Ruby 4.0**, so `x86-mingw32` stops at 3.4; 64-bit
+Windows before Ruby 3.1 used a different platform (`x64-mingw32`), which is not built; and the
+cross-compilation image for `aarch64-mingw-ucrt` carries no cross Ruby older than 3.4, so that
+gem has no floor below it.
+
+### Building from source
 
 Anywhere else — macOS, ARM, the BSDs — RubyGems falls back to the source gem, which downloads and
 builds FreeType, SFML 3 and CSFML 3 from pinned, checksum-verified tarballs at install time. That
@@ -42,36 +72,39 @@ takes a few minutes and needs:
 * Ruby >= 3.1
 * A C/C++ toolchain and CMake >= 3.22
 * On Linux, the X11/udev/OpenGL development headers SFML links against — these can't be bundled.
-  On Fedora:
 
-  ```sh
-  sudo dnf install cmake gcc-c++ libX11-devel \
-    libXrandr-devel libXcursor-devel libXi-devel systemd-devel libglvnd-devel
-  ```
+On Fedora:
 
-  or on Debian/Ubuntu:
+```sh
+sudo dnf install cmake gcc-c++ libX11-devel \
+  libXrandr-devel libXcursor-devel libXi-devel systemd-devel libglvnd-devel
+```
 
-  ```sh
-  sudo apt-get install cmake build-essential libx11-dev \
-    libxrandr-dev libxcursor-dev libxi-dev libudev-dev libgl1-mesa-dev
-  ```
+On Debian/Ubuntu:
+
+```sh
+sudo apt-get install cmake build-essential libx11-dev \
+  libxrandr-dev libxcursor-dev libxi-dev libudev-dev libgl1-mesa-dev
+```
 
 Each installed gem version builds its own copy; there's no build cache shared across versions.
 
+### Linking against system libraries
+
 To link against a system CSFML 3 instead (no download, no build):
 
 ```sh
 gem install sfml3-rb -- --enable-system-libraries
 ```
 
-## Usage
+## Quick Start
 
 ```ruby
 require 'sfml'
 include SFML
 
 window = Window.new VideoMode.new(640, 480, 32), 'SFML'
-event = Event.new
+event  = Event.new
 
 while window.is_open?
   while window.poll_event! event
@@ -83,7 +116,20 @@ while window.is_open?
 end
 ```
 
-See [`test/hello-world.rb`](test/hello-world.rb) for a fuller example with shapes and transforms.
+Event types are strings (`'closed'`, `'resized'`, `'key-pressed'`, ...); keys and buttons are enums.
+
+See [`test/hello-world.rb`](test/hello-world.rb) for a fuller example with shapes and transforms,
+and [`test/matrix-transformable.rb`](test/matrix-transformable.rb) for a visual demo. Neither is
+part of the test suite.
+
+## Documentation
+
+* [API reference](https://rubydoc.info/gems/sfml3-rb) — every class, module, method and constant,
+  built from the YARD comments in `ext/**/*.c`.
+* RBS type signatures (`sig/**/*.rbs`) ship in the gem for IDE completion (Solargraph, RubyMine)
+  and static type-checking (Sorbet, Steep). Validate them with `rake rbs`.
+* [CHANGELOG.md](CHANGELOG.md) — what changed in each release.
+* [TODO.md](TODO.md) — module-by-module porting coverage and what is deliberately unbound.
 
 ## Development
 
@@ -138,9 +184,31 @@ mingw toolchain and the osxcross SDK already provide.
 Binary gems carry one extension per Ruby ABI under `lib/sfml/<major.minor>/`; `lib/sfml.rb` prefers
 that and falls back to the single `lib/sfml/sfml_ext.so` a source build installs.
 
+## Contributing
+
+Bug reports and pull requests are welcome on
+[GitHub](https://github.com/algaves/sfml3.rb/issues). Before opening a pull request:
+
+```sh
+bundle install
+bundle exec rake test   # build the extension and run the suite
+bundle exec rubocop     # lint Ruby (CI enforces this)
+```
+
+Install the pre-commit hook with `bundle exec rake githooks:install` so staged Ruby is linted and
+staged C is formatted automatically. The C build is warning-clean under `SFML_STRICT=1`; keep it
+that way.
+
+## Acknowledgements
+
+This gem would not exist without [SFML](https://www.sfml-dev.org/) and its C binding,
+[CSFML](https://github.com/SFML/CSFML), both maintained by the SFML team. The source build also
+vendors and links FreeType, Ogg, Vorbis and FLAC; see [`ext/ports.rb`](ext/ports.rb) and the
+[LICENSE](LICENSE.md) for their terms.
+
 ## License
 
-[0BSD](LICENSE.md)
+This project is licensed under the BSD Zero Clause License (0BSD) - see the [LICENSE](LICENSE.md) file for details.
 
 ---
 

data/ext/audio/audio_enums.c

@@ -3,12 +3,12 @@
 #include <ruby.h>
 #include <string.h>
 
-static const char *sound_status_names[] = {"stopped", "paused", "playing"};
+static const char* sound_status_names[] = {"stopped", "paused", "playing"};
 
 /* Designated initializers, indexed by the enum constant rather than by
    position: CSFML 3 defines the channel order, and a positional table would
    silently return the wrong name if a future release inserted a value. */
-static const char *sound_channel_names[] = {
+static const char* sound_channel_names[] = {
     [sfSoundChannelUnspecified] = "unspecified",
     [sfSoundChannelMono] = "mono",
     [sfSoundChannelFrontLeft] = "front_left",
@@ -28,11 +28,10 @@ static const char *sound_channel_names[] = {
     [sfSoundChannelTopFrontCenter] = "top_front_center",
     [sfSoundChannelTopBackLeft] = "top_back_left",
     [sfSoundChannelTopBackRight] = "top_back_right",
-    [sfSoundChannelTopBackCenter] = "top_back_center"
-};
+    [sfSoundChannelTopBackCenter] = "top_back_center"};
 
-static int symbol_index(VALUE rb_symbol, const char *const *names, size_t count) {
-    const char *name;
+static int symbol_index(VALUE rb_symbol, const char* const* names, size_t count) {
+    const char* name;
     size_t i;
 
     if (!SYMBOL_P(rb_symbol)) {
@@ -43,14 +42,14 @@ static int symbol_index(VALUE rb_symbol, const char *const *names, size_t count)
 
     for (i = 0; i < count; i++) {
         if (names[i] != NULL && strcmp(name, names[i]) == 0) {
-            return (int) i;
+            return (int)i;
         }
     }
 
     return -1;
 }
 
-const char *sound_status_name(sfSoundStatus status) {
+const char* sound_status_name(sfSoundStatus status) {
     if (status >= sfStopped && status <= sfPlaying) {
         return sound_status_names[status];
     }
@@ -62,7 +61,7 @@ sfSoundStatus sound_status_from_rb(VALUE rb_status) {
     int index;
 
     if (RB_INTEGER_TYPE_P(rb_status)) {
-        return (sfSoundStatus) NUM2INT(rb_status);
+        return (sfSoundStatus)NUM2INT(rb_status);
     }
 
     index = symbol_index(rb_status, sound_status_names, 3);
@@ -71,10 +70,10 @@ sfSoundStatus sound_status_from_rb(VALUE rb_status) {
         rb_raise(rb_eArgError, "unknown sound status");
     }
 
-    return (sfSoundStatus) index;
+    return (sfSoundStatus)index;
 }
 
-const char *sound_channel_name(sfSoundChannel channel) {
+const char* sound_channel_name(sfSoundChannel channel) {
     if (channel >= sfSoundChannelUnspecified && channel <= sfSoundChannelTopBackCenter &&
         sound_channel_names[channel] != NULL) {
         return sound_channel_names[channel];
@@ -87,7 +86,7 @@ sfSoundChannel sound_channel_from_rb(VALUE rb_channel) {
     int index;
 
     if (RB_INTEGER_TYPE_P(rb_channel)) {
-        return (sfSoundChannel) NUM2INT(rb_channel);
+        return (sfSoundChannel)NUM2INT(rb_channel);
     }
 
     index = symbol_index(rb_channel, sound_channel_names,
@@ -97,35 +96,74 @@ sfSoundChannel sound_channel_from_rb(VALUE rb_channel) {
         rb_raise(rb_eArgError, "unknown sound channel");
     }
 
-    return (sfSoundChannel) index;
+    return (sfSoundChannel)index;
 }
 
-void Init_AudioEnums(VALUE rb_module) {
-    VALUE rb_mSoundStatus = rb_define_module_under(rb_module, "SoundStatus");
-    VALUE rb_mSoundChannel = rb_define_module_under(rb_module, "SoundChannel");
-
+/* Document-module: SFML::SoundStatus
+ * Playback state constants returned by SoundSource#status (Sound, Music,
+ * SoundStream). Mirrored as symbols (+:stopped+, +:paused+, +:playing+) by
+ * that method rather than these Integer constants, but both refer to the
+ * same underlying values.
+ */
+
+/* Document-module: SFML::SoundChannel
+ * Speaker position constants used in a channel map (SoundBuffer#channel_map,
+ * Music#channel_map, SoundStream#channel_map, SoundRecorder#channel_map),
+ * mirrored as symbols (e.g. +:front_left+) rather than these Integer
+ * constants in those methods.
+ */
+void Init_AudioEnums(VALUE rb_mSFML) {
+    VALUE rb_mSoundStatus = rb_define_module_under(rb_mSFML, "SoundStatus");
+    VALUE rb_mSoundChannel = rb_define_module_under(rb_mSFML, "SoundChannel");
+
+    /* The source is not playing. */
     rb_define_const(rb_mSoundStatus, "STOPPED", INT2NUM(sfStopped));
+    /* The source is paused; #playing_offset stays where it was paused. */
     rb_define_const(rb_mSoundStatus, "PAUSED", INT2NUM(sfPaused));
+    /* The source is currently playing. */
     rb_define_const(rb_mSoundStatus, "PLAYING", INT2NUM(sfPlaying));
 
+    /* No channel position specified. */
     rb_define_const(rb_mSoundChannel, "UNSPECIFIED", INT2NUM(sfSoundChannelUnspecified));
+    /* A single, centered channel. */
     rb_define_const(rb_mSoundChannel, "MONO", INT2NUM(sfSoundChannelMono));
+    /* Front left speaker. */
     rb_define_const(rb_mSoundChannel, "FRONT_LEFT", INT2NUM(sfSoundChannelFrontLeft));
+    /* Front right speaker. */
     rb_define_const(rb_mSoundChannel, "FRONT_RIGHT", INT2NUM(sfSoundChannelFrontRight));
+    /* Front center speaker. */
     rb_define_const(rb_mSoundChannel, "FRONT_CENTER", INT2NUM(sfSoundChannelFrontCenter));
-    rb_define_const(rb_mSoundChannel, "FRONT_LEFT_OF_CENTER", INT2NUM(sfSoundChannelFrontLeftOfCenter));
-    rb_define_const(rb_mSoundChannel, "FRONT_RIGHT_OF_CENTER", INT2NUM(sfSoundChannelFrontRightOfCenter));
-    rb_define_const(rb_mSoundChannel, "LOW_FREQUENCY_EFFECTS", INT2NUM(sfSoundChannelLowFrequencyEffects));
+    /* Front left-of-center speaker. */
+    rb_define_const(rb_mSoundChannel, "FRONT_LEFT_OF_CENTER",
+                    INT2NUM(sfSoundChannelFrontLeftOfCenter));
+    /* Front right-of-center speaker. */
+    rb_define_const(rb_mSoundChannel, "FRONT_RIGHT_OF_CENTER",
+                    INT2NUM(sfSoundChannelFrontRightOfCenter));
+    /* Low-frequency effects (subwoofer) channel. */
+    rb_define_const(rb_mSoundChannel, "LOW_FREQUENCY_EFFECTS",
+                    INT2NUM(sfSoundChannelLowFrequencyEffects));
+    /* Back left speaker. */
     rb_define_const(rb_mSoundChannel, "BACK_LEFT", INT2NUM(sfSoundChannelBackLeft));
+    /* Back right speaker. */
     rb_define_const(rb_mSoundChannel, "BACK_RIGHT", INT2NUM(sfSoundChannelBackRight));
+    /* Back center speaker. */
     rb_define_const(rb_mSoundChannel, "BACK_CENTER", INT2NUM(sfSoundChannelBackCenter));
+    /* Side left speaker. */
     rb_define_const(rb_mSoundChannel, "SIDE_LEFT", INT2NUM(sfSoundChannelSideLeft));
+    /* Side right speaker. */
     rb_define_const(rb_mSoundChannel, "SIDE_RIGHT", INT2NUM(sfSoundChannelSideRight));
+    /* Top center speaker. */
     rb_define_const(rb_mSoundChannel, "TOP_CENTER", INT2NUM(sfSoundChannelTopCenter));
+    /* Top front left speaker. */
     rb_define_const(rb_mSoundChannel, "TOP_FRONT_LEFT", INT2NUM(sfSoundChannelTopFrontLeft));
+    /* Top front right speaker. */
     rb_define_const(rb_mSoundChannel, "TOP_FRONT_RIGHT", INT2NUM(sfSoundChannelTopFrontRight));
+    /* Top front center speaker. */
     rb_define_const(rb_mSoundChannel, "TOP_FRONT_CENTER", INT2NUM(sfSoundChannelTopFrontCenter));
+    /* Top back left speaker. */
     rb_define_const(rb_mSoundChannel, "TOP_BACK_LEFT", INT2NUM(sfSoundChannelTopBackLeft));
+    /* Top back right speaker. */
     rb_define_const(rb_mSoundChannel, "TOP_BACK_RIGHT", INT2NUM(sfSoundChannelTopBackRight));
+    /* Top back center speaker. */
     rb_define_const(rb_mSoundChannel, "TOP_BACK_CENTER", INT2NUM(sfSoundChannelTopBackCenter));
 }

data/ext/audio/listener.c

@@ -5,68 +5,151 @@
 #include "audio/sound_source_cone.h"
 #include "system/vec3.h"
 
+/* call-seq: global_volume -> Float
+ *
+ * Returns the global volume applied to every sound source in the scene.
+ *
+ * @return [Float] 0 to 100
+ */
 static VALUE Listener_global_volume(VALUE module) {
     return DBL2NUM(sfListener_getGlobalVolume());
 }
 
+/* call-seq:
+ *   global_volume=(value) -> Float
+ *
+ * Sets the global volume all sound sources are scaled by.
+ *
+ * @return [Float] +value+
+ */
 static VALUE Listener_set_global_volume(VALUE module, VALUE rb_value) {
-    sfListener_setGlobalVolume((float) NUM2DBL(rb_value));
+    sfListener_setGlobalVolume((float)NUM2DBL(rb_value));
     return rb_value;
 }
 
+/* call-seq: position -> Vector3
+ *
+ * Returns the listener's position in the 3D audio scene.
+ *
+ * @return [Vector3]
+ */
 static VALUE Listener_position(VALUE module) {
     return vec3f_to_rb(sfListener_getPosition());
 }
 
+/* call-seq:
+ *   position=(value) -> Vector3
+ *
+ * Sets the listener's position in the 3D audio scene.
+ *
+ * @return [Vector3] +value+
+ */
 static VALUE Listener_set_position(VALUE module, VALUE rb_value) {
     sfListener_setPosition(vec3f_from_rb(rb_value));
     return rb_value;
 }
 
+/* call-seq: direction -> Vector3
+ *
+ * Returns the direction the listener is facing, used for spatialization.
+ *
+ * @return [Vector3]
+ */
 static VALUE Listener_direction(VALUE module) {
     return vec3f_to_rb(sfListener_getDirection());
 }
 
+/* call-seq:
+ *   direction=(value) -> Vector3
+ *
+ * Sets the direction the listener is facing.
+ *
+ * @return [Vector3] +value+
+ */
 static VALUE Listener_set_direction(VALUE module, VALUE rb_value) {
     sfListener_setDirection(vec3f_from_rb(rb_value));
     return rb_value;
 }
 
+/* call-seq: velocity -> Vector3
+ *
+ * Returns the listener's velocity, used for Doppler calculations.
+ *
+ * @return [Vector3]
+ */
 static VALUE Listener_velocity(VALUE module) {
     return vec3f_to_rb(sfListener_getVelocity());
 }
 
+/* call-seq:
+ *   velocity=(value) -> Vector3
+ *
+ * Sets the listener's velocity for Doppler calculations.
+ *
+ * @return [Vector3] +value+
+ */
 static VALUE Listener_set_velocity(VALUE module, VALUE rb_value) {
     sfListener_setVelocity(vec3f_from_rb(rb_value));
     return rb_value;
 }
 
+/* call-seq: up_vector -> Vector3
+ *
+ * Returns the listener's up vector, defining its vertical orientation.
+ *
+ * @return [Vector3]
+ */
 static VALUE Listener_up_vector(VALUE module) {
     return vec3f_to_rb(sfListener_getUpVector());
 }
 
+/* call-seq:
+ *   up_vector=(value) -> Vector3
+ *
+ * Sets the listener's up vector, defining its vertical orientation.
+ *
+ * @return [Vector3] +value+
+ */
 static VALUE Listener_set_up_vector(VALUE module, VALUE rb_value) {
     sfListener_setUpVector(vec3f_from_rb(rb_value));
     return rb_value;
 }
 
+/* call-seq: cone -> SoundSourceCone
+ *
+ * Returns the listener's directional attenuation cone.
+ *
+ * @return [SoundSourceCone]
+ */
 static VALUE Listener_cone(VALUE module) {
     sfListenerCone cone = sfListener_getCone();
 
-    return sound_source_cone_to_rb((sfSoundSourceCone) {cone.innerAngle, cone.outerAngle,
-                                                        cone.outerGain});
+    return sound_source_cone_to_rb(
+        (sfSoundSourceCone){cone.innerAngle, cone.outerAngle, cone.outerGain});
 }
 
+/* call-seq:
+ *   cone=(value) -> SoundSourceCone
+ *
+ * Sets the listener's directional attenuation cone.
+ *
+ * @return [SoundSourceCone] +value+
+ */
 static VALUE Listener_set_cone(VALUE module, VALUE rb_value) {
     sfSoundSourceCone cone = sound_source_cone_from_rb(rb_value);
 
-    sfListener_setCone((sfListenerCone) {cone.innerAngle, cone.outerAngle, cone.outerGain});
+    sfListener_setCone((sfListenerCone){cone.innerAngle, cone.outerAngle, cone.outerGain});
 
     return rb_value;
 }
 
-void Init_Listener(VALUE rb_module) {
-    VALUE rb_mListener = rb_define_module_under(rb_module, "Listener");
+/* Document-module: SFML::Listener
+ * Module functions controlling the single global audio listener: its
+ * position, orientation and volume, against which every SoundSource's
+ * spatialization is computed.
+ */
+void Init_Listener(VALUE rb_mSFML) {
+    VALUE rb_mListener = rb_define_module_under(rb_mSFML, "Listener");
 
     rb_define_module_function(rb_mListener, "global_volume", Listener_global_volume, 0);
     rb_define_module_function(rb_mListener, "global_volume=", Listener_set_global_volume, 1);