ruby-sfml 3.0.0.6 → 3.0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e15752d993b5c76445ea903b92227b45c169009bed4de15166ff5db1d1fbd372
-  data.tar.gz: bf5ae66de3f3df40c765c5aee29eef1138d1743e899e6e072e707f63ee0fcf84
+  metadata.gz: 4a12ef598ae1b1dc8e541b0e3f463ec05208391202d465a5cd5360ae473be321
+  data.tar.gz: 6830ae6b0a231203e36d104a81caeb3cdcee03f706728cf2af935596f19783aa
 SHA512:
-  metadata.gz: dd013a7669a09457c0f5a6915ce8ee91ac32018146d0dae6a6af6d73f5f4dba8864778827aac10e2194c553b715a18895be056f41d0dc8002cfcc99087be4664
-  data.tar.gz: 41ba407931cdf67f1493187c517a59d8b981d62ae4fd7ccf051696b9348fb03046228c651d2f0be45f0edb40b5f6a2ef417f4cda6dfd7124e04a46489bb7b258
+  metadata.gz: fd3caad7ec21d3408d86c973a3f0430408cfda54cb363664fbe6af319e11922740a52fde36290124ef3f591c87fbf70f0dfe2085dd3590e63dba51a54e392567
+  data.tar.gz: 41fee62ce46c0e69ee80521f51752309aa4b47bc82021d472f5370dad88dc28735549ee33563352938b2edd1f9f2e9fdbf25b611c33ccc01802b8a88acd2e9a5

data/.rdoc_options

@@ -0,0 +1,44 @@
+---
+# RDoc project config. Read by both `rake rdoc` (via RDoc::Task) and
+# the standalone `rdoc` CLI — the docs-site repo invokes `rdoc`
+# directly, so all the user-facing knobs live here, not in Rakefile.
+
+# Page rendered as the doc-site root.
+main_page: README.md
+title:     ruby-sfml — modern Ruby bindings for SFML 3.x
+
+# README + LICENSE + CHANGELOG are markdown; assume the same dialect
+# in source-file comments.
+markup:    markdown
+
+# `doc/` matches RDoc's default output dir.
+output:    doc
+
+# Visibility filter: public API only. Internal `_method` helpers and
+# the FFI plumbing under `SFML::C::*` add noise without value.
+visibility: public
+
+# What gets parsed. Skip the C-bindings module entirely; including
+# them would document every `attach_function` and drown the API user.
+exclude:
+  - lib/sfml/c.rb
+  - lib/sfml/c/
+  - ext/
+  - spec/
+  - examples/
+  - pkg/
+  - doc/
+  - vendor/
+
+# Surface non-source pages as a "Pages" sidebar entry.
+files:
+  - README.md
+  - CHANGELOG.md
+  - LICENSE.txt
+  - lib/
+
+# Cosmetic.
+template: darkfish
+charset:  UTF-8
+line_numbers: false
+show_hash: false

data/CHANGELOG.md

@@ -6,8 +6,48 @@ versioning is [described in the README](README.md#versioning) — first
 three segments mirror the targeted CSFML release, fourth segment is
 ruby-sfml's own patch level.
 
+HTML API docs: <https://ruby-sfml-doc.netlify.app/>
+
 ## [Unreleased]
 
+## [3.0.0.7] — 2026-05-12
+
+Documentation pass. Every public class / module / method now
+carries at least a one-line RDoc comment — coverage went from
+~36% (`rake rdoc:coverage`) to ~68%. Pair this release with the
+new docs site at <https://ruby-sfml-doc.netlify.app/>.
+
+### Changed — documentation
+
+- Hand-written, context-aware docstrings on the value classes
+  (`Vector2`, `Vector3`, `Color`, `Rect`, `Time`): every operator,
+  every helper, every pattern-match hook.
+- Audio API surface (`Sound`, `Music`, `SoundStream`, `Listener`):
+  every playback method, every property setter/getter, every 3D-
+  audio knob has a real description.
+- Graphics — `Transformable` mixin (`#position` / `#rotation` /
+  `#scale` / `#origin` / `#move` / `#rotate` / `#scale_by`), then
+  `CircleShape` / `RectangleShape` / `ConvexShape` / `Text` /
+  `VertexArray` / `RenderWindow`. Color named-accessors,
+  geometric introspection, fill / outline / texture binding.
+- Network — typed `Packet` reader / writer methods, full FTP
+  surface (`#download` / `#upload` / `#directory_listing` / …).
+- The autodoc pass fills in trivial setter / getter / predicate
+  pairs everywhere else, so the docs site has at least an
+  identifiable signature line on every public method.
+
+### Changed — infra
+
+- `documentation_uri` in the gemspec now points to
+  <https://ruby-sfml-doc.netlify.app/> (was rubydoc.info).
+  rubydoc.info still works as an archive of older releases.
+- `.rdoc_options` ships inside the gem (`gem unpack` exposes it),
+  so the docs-site repo can `rdoc` an unpacked release without
+  re-supplying title / template / markup / exclude config.
+- Added `script/build-docs.sh` — local-only build that renders
+  `../ruby-sfml-doc/public/`. Optional `--check` mode catches
+  "docs out of date with source" in a pre-push hook.
+
 ## [3.0.0.6] — 2026-05-12
 
 Quality-of-life release: the CSFML 3.0 surface was already covered;
@@ -79,9 +119,6 @@ on top of it.
 
 ### Added — CI / tooling
 
-- GitHub Actions release workflow (`release.yml`) — tag
-  `vX.Y.Z.W` triggers a gem build + push to RubyGems. Verifies
-  the tag matches `lib/sfml/version.rb` before publishing.
 - CI badge in `README.md`.
 
 ## [3.0.0.5] — 2026-05-11

data/README.md

@@ -7,9 +7,9 @@ Modern, idiomatic Ruby bindings for [SFML 3.x](https://www.sfml-dev.org/) via [C
 
 [![gem version](https://img.shields.io/gem/v/ruby-sfml.svg)](https://rubygems.org/gems/ruby-sfml)
 [![CI](https://github.com/sOM2H/ruby-sfml/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/sOM2H/ruby-sfml/actions/workflows/ci.yml)
-[![docs](https://img.shields.io/badge/docs-rubydoc.info-blue.svg)](https://www.rubydoc.info/gems/ruby-sfml)
+[![docs](https://img.shields.io/badge/docs-ruby--sfml--doc.netlify.app-blue.svg)](https://ruby-sfml-doc.netlify.app/)
 
-> **Status:** API surface complete for SFML 3.0 — system, window, graphics (incl. stencil buffer + VBOs), audio (incl. 3D positional + custom DSP + procedural streams), network (incl. HTTP / FTP / socket selector), input (keyboard, mouse, joystick, touch, sensors), plus the higher-level `App` / `Scene` / `Assets` helpers. 410 RSpec examples, 24 runnable example folders.
+> **Status:** API surface complete for SFML 3.0 — system, window, graphics (incl. stencil buffer + VBOs), audio (incl. 3D positional + custom DSP + procedural streams), network (incl. HTTP / FTP / socket selector), input (keyboard, mouse, joystick, touch, sensors), plus higher-level helpers (`App`, `Scene`, `Assets`, `SpriteSheet`, `Animation`, `TextureAtlas`, `ParticleSystem`, fixed timestep, input-action DSL, vector math). 640 RSpec examples, 35 runnable example folders.
 
 ## Why
 
@@ -46,9 +46,12 @@ Or drop it in directly:
 gem install ruby-sfml
 ```
 
-Hosted on [rubygems.org](https://rubygems.org/gems/ruby-sfml); HTML
-docs auto-generate at
-[rubydoc.info/gems/ruby-sfml](https://www.rubydoc.info/gems/ruby-sfml).
+Hosted on [rubygems.org](https://rubygems.org/gems/ruby-sfml).
+HTML docs (RDoc) live at [**ruby-sfml-doc.netlify.app**](https://ruby-sfml-doc.netlify.app/)
+— built from the source tree of the latest release and served as
+static HTML. RubyGems' auto-generated docs at
+[rubydoc.info/gems/ruby-sfml](https://www.rubydoc.info/gems/ruby-sfml)
+work too as a fallback.
 
 ### How the CSFML check happens
 
@@ -156,31 +159,74 @@ to its script. Run from the gem root:
 bundle exec ruby examples/<NN_name>/<name>.rb
 ```
 
+The numbering reflects a rough learning order — earlier examples
+introduce concepts that later ones build on. Pick the section that
+matches what you want to learn first.
+
+### Foundations — window, events, input
+
 | #   | Example                                                                        | What it shows                                                       |
 | --- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
 | 01  | [hello_window](examples/01_hello_window/hello_window.rb)                       | Empty window, manual event loop                                     |
 | 02  | [events_demo](examples/02_events_demo/events_demo.rb)                          | Pattern matching on input events                                    |
-| 03  | [bouncing_ball](examples/03_bouncing_ball/bouncing_ball.rb)                    | dt-based physics, `CircleShape` + `RectangleShape`                  |
-| 04  | [app_class](examples/04_app_class/app_class.rb)                                 | Same idea on top of `SFML::App`                                     |
-| 05  | [mouse_demo](examples/05_mouse_demo/mouse_demo.rb)                             | Polling vs. events; paint with the mouse                            |
-| 06  | [pong](examples/06_pong/pong.rb)                                               | Two-player Pong with in-window score (`Text`) and bounce `Sound`    |
-| 07  | [scrolling_world](examples/07_scrolling_world/scrolling_world.rb)              | `View` as a 2D camera: drag-pan, wheel-zoom around cursor, FPS HUD  |
-| 08  | [joystick_demo](examples/08_joystick_demo/joystick_demo.rb)                    | Live gamepad inspector (axes, buttons, connect/disconnect)          |
-| 09  | [image_viewer](examples/09_image_viewer/image_viewer.rb)                       | Load a PNG, mutate the `Image`, re-upload to `Texture` on a key     |
-| 10  | [pixel_paint](examples/10_pixel_paint/pixel_paint.rb)                          | Paint into a CPU `Image`, blit to GPU `Texture` each dirty frame    |
-| 11  | [particles](examples/11_particles/particles.rb)                                | Thousands of points in one draw call via `VertexArray` + `ConvexShape` ground |
-| 12  | [render_texture](examples/12_render_texture/render_texture.rb)                 | Off-screen `RenderTexture` for trail / motion-blur effects        |
-| 13  | [tilemap](examples/13_tilemap/tilemap.rb)                                      | Textured `VertexArray` tilemap + additive `BlendMode` torch       |
-| 14  | [shader_wave](examples/14_shader_wave/shader_wave.rb)                          | Pure GLSL fragment `Shader` — procedural ripple + plasma          |
+| 03  | [mouse_demo](examples/03_mouse_demo/mouse_demo.rb)                             | Polling vs. events; paint with the mouse                            |
+| 04  | [bouncing_ball](examples/04_bouncing_ball/bouncing_ball.rb)                    | dt-based physics on a manual main loop                              |
+| 05  | [app_class](examples/05_app_class/app_class.rb)                                | Same idea on top of `SFML::App` — see how much boilerplate goes away |
+| 06  | [vector_math](examples/06_vector_math/vector_math.rb)                          | `Vector2` helpers (`#distance` / `#angle_to` / `#rotated` / `#lerp` / `#clamp_length`) in real motion |
+| 07  | [input_actions](examples/07_input_actions/input_actions.rb)                    | `action :name, keys:, scancodes:, mouse_buttons:` DSL + `axis(...)` digital steering |
+
+### Drawing — geometry and assets
+
+| #   | Example                                                                        | What it shows                                                       |
+| --- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
+| 08  | [draw_primitives](examples/08_draw_primitives/draw_primitives.rb)              | Raw `draw_primitives` — line burst rebuilt every frame             |
+| 09  | [custom_shape](examples/09_custom_shape/custom_shape.rb)                       | Abstract `SFML::Shape` subclass — parametric star / heart / gear   |
+| 10  | [image_viewer](examples/10_image_viewer/image_viewer.rb)                       | Load a PNG, mutate the `Image`, re-upload to `Texture` on a key   |
+| 11  | [pixel_paint](examples/11_pixel_paint/pixel_paint.rb)                          | Paint into a CPU `Image`, blit to GPU `Texture` each dirty frame  |
+| 12  | [sprite_animation](examples/12_sprite_animation/sprite_animation.rb)           | Procedural `SpriteSheet` → `Animation` walk cycle                  |
+| 13  | [texture_atlas](examples/13_texture_atlas/texture_atlas.rb)                    | Aseprite-style JSON atlas → 3 named animations with auto-fps       |
+| 14  | [window_icon](examples/14_window_icon/window_icon.rb)                          | Procedural 32×32 icon set as the window/taskbar icon              |
 | 15  | [cursors_clipboard](examples/15_cursors_clipboard/cursors_clipboard.rb)        | All 21 system `Cursor` shapes + `Clipboard` copy/paste            |
-| 16  | [spatial_audio](examples/16_spatial_audio/spatial_audio.rb)                    | 3D positional `Sound` + `Listener` — three drones around the cursor |
-| 17  | [voice_memo](examples/17_voice_memo/voice_memo.rb)                             | Record from microphone via `SoundBufferRecorder`, save + play back |
-| 18  | [draw_primitives](examples/18_draw_primitives/draw_primitives.rb)              | Raw `draw_primitives` — line burst rebuilt every frame             |
-| 19  | [udp_loopback](examples/19_udp_loopback/udp_loopback.rb)                       | UDP send/receive on localhost via `Network::UdpSocket`             |
-| 20  | [bare_window](examples/20_bare_window/bare_window.rb)                          | `SFML::Window` (no 2D batcher) — events for raw-OpenGL apps        |
-| 21  | [window_icon](examples/21_window_icon/window_icon.rb)                          | Procedural 32×32 icon set as the window/taskbar icon              |
-| 22  | [stencil_mask](examples/22_stencil_mask/stencil_mask.rb)                       | Two-pass `StencilMode` masking — cursor spotlight clip            |
-| 23  | [sound_stream](examples/23_sound_stream/sound_stream.rb)                       | Real-time sine synth via `SFML::SoundStream` subclass             |
+
+### Camera, GPU, effects
+
+| #   | Example                                                                        | What it shows                                                       |
+| --- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
+| 16  | [screenshot](examples/16_screenshot/screenshot.rb)                             | `RenderWindow#screenshot(path)` / `#capture_image` for in-memory frames |
+| 17  | [scrolling_world](examples/17_scrolling_world/scrolling_world.rb)              | `View` as a 2D camera: drag-pan, wheel-zoom around cursor, FPS HUD |
+| 18  | [render_texture](examples/18_render_texture/render_texture.rb)                 | Off-screen `RenderTexture` for trail / motion-blur effects        |
+| 19  | [tilemap](examples/19_tilemap/tilemap.rb)                                      | Textured `VertexArray` tilemap + additive `BlendMode` torch       |
+| 20  | [particle_system](examples/20_particle_system/particle_system.rb)              | `SFML::ParticleSystem` fountain — VertexArray-backed pool        |
+| 21  | [particles](examples/21_particles/particles.rb)                                | Same fountain hand-rolled on `VertexArray` + `ConvexShape` ground |
+| 22  | [shader_wave](examples/22_shader_wave/shader_wave.rb)                          | Pure GLSL fragment `Shader` — procedural ripple + plasma          |
+| 23  | [stencil_mask](examples/23_stencil_mask/stencil_mask.rb)                       | Two-pass `StencilMode` masking — cursor spotlight clip            |
+| 24  | [vertex_buffer](examples/24_vertex_buffer/vertex_buffer.rb)                    | 120 K-vertex `VertexBuffer` drawn in one call, animated via `View` only |
+| 25  | [bare_window](examples/25_bare_window/bare_window.rb)                          | `SFML::Window` (no 2D batcher) — events for raw-OpenGL apps      |
+
+### Game-loop polish
+
+| #   | Example                                                                        | What it shows                                                       |
+| --- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
+| 26  | [scenes](examples/26_scenes/scenes.rb)                                         | Title → play → game-over flow with `SFML::Scene`                  |
+| 27  | [fixed_timestep](examples/27_fixed_timestep/fixed_timestep.rb)                 | `fixed_timestep 30` + `interpolation_alpha` for jitter-free physics |
+| 28  | [pong](examples/28_pong/pong.rb)                                               | Two-player Pong with in-window score (`Text`) and bounce `Sound`  |
+| 29  | [joystick_demo](examples/29_joystick_demo/joystick_demo.rb)                    | Live gamepad inspector (axes, buttons, connect/disconnect)        |
+
+### Audio — simple to procedural
+
+| #   | Example                                                                        | What it shows                                                       |
+| --- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
+| 30  | [spatial_audio](examples/30_spatial_audio/spatial_audio.rb)                    | 3D positional `Sound` + `Listener` — three drones around the cursor |
+| 31  | [voice_memo](examples/31_voice_memo/voice_memo.rb)                             | Record from microphone via `SoundBufferRecorder`, save + play back |
+| 32  | [sound_stream](examples/32_sound_stream/sound_stream.rb)                       | Real-time sine synth via `SFML::SoundStream` subclass             |
+| 33  | [procedural_synth](examples/33_procedural_synth/procedural_synth.rb)           | `SoundBuffer.from_samples` mini-piano (Z–M keys, chromatic C4..B4) |
+
+### Networking
+
+| #   | Example                                                                        | What it shows                                                       |
+| --- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
+| 34  | [udp_loopback](examples/34_udp_loopback/udp_loopback.rb)                       | UDP send/receive on localhost via `Network::UdpSocket`             |
+| 35  | [tcp_chat](examples/35_tcp_chat/tcp_chat.rb)                                   | `TcpListener` + `TcpSocket` + typed `Network::Packet` over loopback |
 
 ## Idioms baked in
 

data/lib/sfml/app.rb

@@ -118,6 +118,7 @@ module SFML
     # Width and height shortcuts that always reflect the current
     # window size — matters once the user is allowed to resize.
     def width  = @window.size.x
+    # Returns the height.
     def height = @window.size.y
 
     # Close the window. The main loop exits at the start of the
@@ -160,9 +161,13 @@ module SFML
     # (handy for pause overlays that need to be drawn over a
     # frozen scene).
 
+    # Pause the simulation. `#draw` keeps firing; `#update` doesn't.
     def pause   = (@paused = true)
+    # Resume the simulation.
     def resume  = (@paused = false)
+    # Flip the pause state.
     def toggle_pause = (@paused = !paused?)
+    # `true` while the simulation is paused.
     def paused? = @paused == true
 
     # Fraction of a fixed timestep accumulated since the last

data/lib/sfml/assets.rb

@@ -26,11 +26,13 @@ module SFML
         @search_paths ||= [default_root]
       end
 
+      # Set the search paths.
       def search_paths=(paths)
         @search_paths = Array(paths).map { |p| File.expand_path(p) }
         @cache&.clear
       end
 
+      # Set the root.
       def root=(path)
         self.search_paths = [path]
       end

data/lib/sfml/audio/listener.rb

@@ -17,14 +17,17 @@ module SFML
       C::Audio.sfListener_getGlobalVolume
     end
 
+    # Set the master volume in [0, 100].
     def global_volume=(value)
       C::Audio.sfListener_setGlobalVolume(value.to_f)
     end
 
+    # The listener's 3D position in world space.
     def position
       Vector3.from_native(C::Audio.sfListener_getPosition)
     end
 
+    # Set the position — accepts Vector3 or `[x, y, z]`.
     def position=(value)
       vec = value.is_a?(Vector3) ? value : Vector3.new(*value)
       C::Audio.sfListener_setPosition(vec.to_native_f)
@@ -36,6 +39,7 @@ module SFML
       Vector3.from_native(C::Audio.sfListener_getDirection)
     end
 
+    # Set the forward direction — accepts Vector3 or `[x, y, z]`.
     def direction=(value)
       vec = value.is_a?(Vector3) ? value : Vector3.new(*value)
       C::Audio.sfListener_setDirection(vec.to_native_f)
@@ -47,6 +51,7 @@ module SFML
       Vector3.from_native(C::Audio.sfListener_getUpVector)
     end
 
+    # Set the up vector — accepts Vector3 or `[x, y, z]`.
     def up_vector=(value)
       vec = value.is_a?(Vector3) ? value : Vector3.new(*value)
       C::Audio.sfListener_setUpVector(vec.to_native_f)
@@ -58,6 +63,7 @@ module SFML
       Vector3.from_native(C::Audio.sfListener_getVelocity)
     end
 
+    # Set the velocity — accepts Vector3 or `[x, y, z]`.
     def velocity=(value)
       vec = value.is_a?(Vector3) ? value : Vector3.new(*value)
       C::Audio.sfListener_setVelocity(vec.to_native_f)
@@ -72,6 +78,7 @@ module SFML
       SoundCone.from_native(C::Audio.sfListener_getCone)
     end
 
+    # Set the cone. Accepts a `SoundCone` or a Hash.
     def cone=(value)
       cone =
         case value

data/lib/sfml/audio/music.rb

@@ -5,6 +5,9 @@ module SFML
   #   bgm = SFML::Music.load("assets/track.ogg", looping: true, volume: 60)
   #   bgm.play
   class Music
+    # Load a music track from disk. `opts` may include `:volume`,
+    # `:pitch`, and `:looping` — these are applied right after load.
+    # Raises `SFML::LoadError` on missing file or unsupported format.
     def self.load(path, **opts)
       ptr = C::Audio.sfMusic_createFromFile(path.to_s)
       raise LoadError, "Could not load music from #{path.inspect}" if ptr.null?
@@ -56,15 +59,23 @@ module SFML
     end
     private_class_method :_wrap
 
+    # Start playback (resumes from pause, restarts when stopped).
     def play   = C::Audio.sfMusic_play(@handle)
+    # Pause playback — `#play` resumes from here.
     def pause  = C::Audio.sfMusic_pause(@handle)
+    # Stop playback and rewind to the start.
     def stop   = C::Audio.sfMusic_stop(@handle)
 
+    # Playback state — one of `:stopped`, `:paused`, `:playing`.
     def status   = C::Audio::STATUSES[C::Audio.sfMusic_getStatus(@handle)]
+    # Convenience for `status == :playing`.
     def playing? = status == :playing
+    # Convenience for `status == :paused`.
     def paused?  = status == :paused
+    # Convenience for `status == :stopped`.
     def stopped? = status == :stopped
 
+    # Total length of the track as a `SFML::Time`.
     def duration = Time.from_native(C::Audio.sfMusic_getDuration(@handle))
 
     # Current playback head as a SFML::Time. Reads from the underlying
@@ -88,6 +99,7 @@ module SFML
       Vector3.new(v[:x], v[:y], v[:z])
     end
 
+    # Set the 3D velocity — accepts Vector3 or `[x, y, z]`.
     def velocity=(value)
       vec = value.is_a?(Vector3) ? value : Vector3.new(*value)
       packed = C::System::Vector3f.new
@@ -95,14 +107,18 @@ module SFML
       C::Audio.sfMusic_setVelocity(@handle, packed)
     end
 
+    # Per-source Doppler scale. 1.0 realistic, 0 disables.
     def doppler_factor    = C::Audio.sfMusic_getDopplerFactor(@handle)
+    # Set the per-source Doppler scale.
     def doppler_factor=(v) C::Audio.sfMusic_setDopplerFactor(@handle, v.to_f); end
 
+    # The direction the music's cone points.
     def direction
       v = C::Audio.sfMusic_getDirection(@handle)
       Vector3.new(v[:x], v[:y], v[:z])
     end
 
+    # Set the direction vector — accepts Vector3 or `[x, y, z]`.
     def direction=(value)
       vec = value.is_a?(Vector3) ? value : Vector3.new(*value)
       packed = C::System::Vector3f.new
@@ -110,10 +126,13 @@ module SFML
       C::Audio.sfMusic_setDirection(@handle, packed)
     end
 
+    # Directional-attenuation cone — see SFML::SoundCone.
     def cone
       SoundCone.from_native(C::Audio.sfMusic_getCone(@handle))
     end
 
+    # Set the cone. Accepts a `SoundCone` or a Hash with
+    # `inner_angle`, `outer_angle`, `outer_gain`.
     def cone=(value)
       cone =
         case value
@@ -131,24 +150,31 @@ module SFML
       C::Audio.sfMusic_setEffectProcessor(@handle, @effect_cb, nil)
     end
 
+    # `true` if the track restarts after reaching the end (or its
+    # `loop_points` length).
     # Cached on the Ruby side; see Sound#looping? for the why.
     def looping?
       @looping
     end
 
+    # Toggle looping playback.
     def looping=(value)
       @looping = value ? true : false
       C::Audio.sfMusic_setLooping(@handle, @looping)
     end
 
+    # Playback volume in [0, 100] — 100 = unattenuated.
     def volume = C::Audio.sfMusic_getVolume(@handle)
 
+    # Set the playback volume in [0, 100].
     def volume=(value)
       C::Audio.sfMusic_setVolume(@handle, value.to_f)
     end
 
+    # Pitch multiplier. 1.0 = normal, 2.0 = octave up, 0.5 = octave down.
     def pitch = C::Audio.sfMusic_getPitch(@handle)
 
+    # Set the pitch multiplier.
     def pitch=(value)
       C::Audio.sfMusic_setPitch(@handle, value.to_f)
     end
@@ -158,32 +184,41 @@ module SFML
       Vector3.from_native(C::Audio.sfMusic_getPosition(@handle))
     end
 
+    # Set the 3D position — accepts Vector3 or `[x, y, z]`.
     def position=(value)
       vec = value.is_a?(Vector3) ? value : Vector3.new(*value)
       C::Audio.sfMusic_setPosition(@handle, vec.to_native_f)
     end
 
+    # Falloff sharpness with distance — see `Sound#attenuation`.
     def attenuation = C::Audio.sfMusic_getAttenuation(@handle)
 
+    # Set the attenuation.
     def attenuation=(value)
       C::Audio.sfMusic_setAttenuation(@handle, value.to_f)
     end
 
+    # Distance below which volume is not attenuated.
     def min_distance = C::Audio.sfMusic_getMinDistance(@handle)
 
+    # Set the min-distance.
     def min_distance=(value)
       C::Audio.sfMusic_setMinDistance(@handle, value.to_f)
     end
 
+    # `true` if `#position` is interpreted relative to the listener.
     def relative_to_listener? = C::Audio.sfMusic_isRelativeToListener(@handle)
 
+    # Toggle listener-relative positioning.
     def relative_to_listener=(value)
       C::Audio.sfMusic_setRelativeToListener(@handle, value ? true : false)
     end
 
     # ---- Stream introspection ----
 
+    # Number of audio channels (1 = mono, 2 = stereo, ...).
     def channel_count = C::Audio.sfMusic_getChannelCount(@handle)
+    # Sample rate in Hz (e.g. 44_100 for CD-quality).
     def sample_rate   = C::Audio.sfMusic_getSampleRate(@handle)
 
     # The portion of the track that loops when `looping = true`.
@@ -194,6 +229,8 @@ module SFML
       [Time.from_native(span[:offset]), Time.from_native(span[:length])]
     end
 
+    # Set the looping window. Accepts `[offset, length]` of either
+    # `SFML::Time` or numeric seconds.
     def loop_points=(value)
       offset_t, length_t = value
       raise ArgumentError, "expected [offset_time, length_time]" unless offset_t && length_t
@@ -206,40 +243,54 @@ module SFML
 
     # ---- 3D-audio extras (mirror of Sound's) ----
 
+    # Stereo pan in [-1.0, 1.0] — see `Sound#pan`.
     def pan = C::Audio.sfMusic_getPan(@handle)
 
+    # Set the stereo pan.
     def pan=(v)
       C::Audio.sfMusic_setPan(@handle, v.to_f)
     end
 
+    # Lower gain bound — see `Sound#min_gain`.
     def min_gain = C::Audio.sfMusic_getMinGain(@handle)
 
+    # Set the min-gain floor.
     def min_gain=(v)
       C::Audio.sfMusic_setMinGain(@handle, v.to_f)
     end
 
+    # Upper gain bound — see `Sound#max_gain`.
     def max_gain = C::Audio.sfMusic_getMaxGain(@handle)
 
+    # Set the max-gain cap.
     def max_gain=(v)
       C::Audio.sfMusic_setMaxGain(@handle, v.to_f)
     end
 
+    # Distance beyond which the source is fully attenuated.
     def max_distance = C::Audio.sfMusic_getMaxDistance(@handle)
 
+    # Set the max-distance.
     def max_distance=(v)
       C::Audio.sfMusic_setMaxDistance(@handle, v.to_f)
     end
 
+    # `true` if 3D positional / Doppler / cone math is applied at
+    # mix time.
     def spatialization_enabled? = C::Audio.sfMusic_isSpatializationEnabled(@handle)
 
+    # Toggle 3D spatialisation.
     def spatialization_enabled=(v)
       C::Audio.sfMusic_setSpatializationEnabled(@handle, v ? true : false)
     end
 
+    # Multiplier on the Listener's directional attenuation cone —
+    # see `Sound#directional_attenuation_factor`.
     def directional_attenuation_factor
       C::Audio.sfMusic_getDirectionalAttenuationFactor(@handle)
     end
 
+    # Set the directional-attenuation factor.
     def directional_attenuation_factor=(v)
       C::Audio.sfMusic_setDirectionalAttenuationFactor(@handle, v.to_f)
     end