ruby-sfml 3.0.0.6 → 3.0.0.7

data/lib/sfml/audio/sound.rb

@@ -26,19 +26,29 @@ module SFML
 
     attr_reader :buffer
 
+    # Replace the `SoundBuffer` this Sound is bound to. Stopping
+    # first is recommended — otherwise the change takes effect mid-frame.
     def buffer=(new_buffer)
       raise ArgumentError, "Sound#buffer= requires a SFML::SoundBuffer" unless new_buffer.is_a?(SoundBuffer)
       C::Audio.sfSound_setBuffer(@handle, new_buffer.handle)
       @buffer = new_buffer
     end
 
+    # Start playback. If the sound was paused, resumes from there.
+    # If it was already playing, restarts from the beginning.
     def play   = C::Audio.sfSound_play(@handle)
+    # Pause playback. `#play` resumes from this point; `#stop` rewinds.
     def pause  = C::Audio.sfSound_pause(@handle)
+    # Stop playback and rewind to the start.
     def stop   = C::Audio.sfSound_stop(@handle)
 
+    # Playback state — one of `:stopped`, `:paused`, `:playing`.
     def status      = C::Audio::STATUSES[C::Audio.sfSound_getStatus(@handle)]
+    # Convenience predicate for `status == :playing`.
     def playing?    = status == :playing
+    # Convenience predicate for `status == :paused`.
     def paused?     = status == :paused
+    # Convenience predicate for `status == :stopped`.
     def stopped?    = status == :stopped
 
     # Current playback head as a SFML::Time. Reads from the underlying
@@ -64,6 +74,7 @@ module SFML
       Vector3.new(v[:x], v[:y], v[:z])
     end
 
+    # Set the 3D velocity — accepts a Vector3 or `[x, y, z]`.
     def velocity=(value)
       vec = value.is_a?(Vector3) ? value : Vector3.new(*value)
       packed = C::System::Vector3f.new
@@ -74,6 +85,7 @@ module SFML
     # Per-source Doppler scale. 1.0 is realistic; bump it up for an
     # exaggerated Doppler shift, drop to 0 to disable per-source.
     def doppler_factor    = C::Audio.sfSound_getDopplerFactor(@handle)
+    # Set the per-source Doppler scale. See `#doppler_factor`.
     def doppler_factor=(v) C::Audio.sfSound_setDopplerFactor(@handle, v.to_f); end
 
     # The direction the sound's cone points. Used together with
@@ -83,6 +95,7 @@ module SFML
       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
@@ -95,6 +108,8 @@ module SFML
       SoundCone.from_native(C::Audio.sfSound_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
@@ -123,23 +138,31 @@ module SFML
       C::Audio.sfSound_setEffectProcessor(@handle, @effect_cb, nil)
     end
 
+    # `true` if the sound restarts after reaching the end.
     def looping?
       @looping
     end
 
+    # Toggle looping playback. With `true`, the sound restarts from
+    # the start after every play-through.
     def looping=(value)
       @looping = value ? true : false
       C::Audio.sfSound_setLooping(@handle, @looping)
     end
 
+    # Playback volume in [0, 100] — 100 = unattenuated.
     def volume      = C::Audio.sfSound_getVolume(@handle)
 
+    # Set the playback volume in [0, 100].
     def volume=(value)
       C::Audio.sfSound_setVolume(@handle, value.to_f)
     end
 
+    # Pitch multiplier. 1.0 = normal, 2.0 = octave up, 0.5 = octave
+    # down. Also shifts playback duration proportionally.
     def pitch       = C::Audio.sfSound_getPitch(@handle)
 
+    # Set the pitch multiplier — see `#pitch`.
     def pitch=(value)
       C::Audio.sfSound_setPitch(@handle, value.to_f)
     end
@@ -158,25 +181,35 @@ module SFML
       Vector3.from_native(C::Audio.sfSound_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.sfSound_setPosition(@handle, vec.to_native_f)
     end
 
+    # Falloff sharpness with distance. 0 = no falloff, 1 = realistic
+    # (1/distance), higher = steeper.
     def attenuation = C::Audio.sfSound_getAttenuation(@handle)
 
+    # Set the attenuation — see `#attenuation`.
     def attenuation=(value)
       C::Audio.sfSound_setAttenuation(@handle, value.to_f)
     end
 
+    # Distance below which volume is not attenuated.
     def min_distance = C::Audio.sfSound_getMinDistance(@handle)
 
+    # Set the min-distance — see `#min_distance`.
     def min_distance=(value)
       C::Audio.sfSound_setMinDistance(@handle, value.to_f)
     end
 
+    # If `true`, `#position` is interpreted relative to the listener
+    # (useful for HUD/UI sounds that should stay glued to the
+    # camera).
     def relative_to_listener? = C::Audio.sfSound_isRelativeToListener(@handle)
 
+    # Toggle listener-relative positioning.
     def relative_to_listener=(value)
       C::Audio.sfSound_setRelativeToListener(@handle, value ? true : false)
     end
@@ -193,6 +226,7 @@ module SFML
     # Stereo pan in [-1.0, 1.0]: -1 = full left, 0 = centre, 1 = full right.
     def pan = C::Audio.sfSound_getPan(@handle)
 
+    # Set the stereo pan — see `#pan`.
     def pan=(v)
       C::Audio.sfSound_setPan(@handle, v.to_f)
     end
@@ -203,12 +237,15 @@ module SFML
     # the listener's local SFX volume).
     def min_gain = C::Audio.sfSound_getMinGain(@handle)
 
+    # Set the min-gain floor — see `#min_gain`.
     def min_gain=(v)
       C::Audio.sfSound_setMinGain(@handle, v.to_f)
     end
 
+    # The upper gain bound — see `#min_gain`.
     def max_gain = C::Audio.sfSound_getMaxGain(@handle)
 
+    # Set the max-gain cap — see `#max_gain`.
     def max_gain=(v)
       C::Audio.sfSound_setMaxGain(@handle, v.to_f)
     end
@@ -216,6 +253,7 @@ module SFML
     # The distance beyond which the source is fully attenuated.
     def max_distance = C::Audio.sfSound_getMaxDistance(@handle)
 
+    # Set the max-distance — see `#max_distance`.
     def max_distance=(v)
       C::Audio.sfSound_setMaxDistance(@handle, v.to_f)
     end
@@ -224,6 +262,7 @@ module SFML
     # mix time. Off → the sound plays as a simple stereo source.
     def spatialization_enabled? = C::Audio.sfSound_isSpatializationEnabled(@handle)
 
+    # Toggle 3D spatialisation — see `#spatialization_enabled?`.
     def spatialization_enabled=(v)
       C::Audio.sfSound_setSpatializationEnabled(@handle, v ? true : false)
     end
@@ -235,6 +274,8 @@ module SFML
       C::Audio.sfSound_getDirectionalAttenuationFactor(@handle)
     end
 
+    # Set the directional-attenuation factor — see
+    # `#directional_attenuation_factor`.
     def directional_attenuation_factor=(v)
       C::Audio.sfSound_setDirectionalAttenuationFactor(@handle, v.to_f)
     end

data/lib/sfml/audio/sound_buffer.rb

@@ -79,9 +79,13 @@ module SFML
       sb
     end
 
+    # Returns the duration.
     def duration      = Time.from_native(C::Audio.sfSoundBuffer_getDuration(@handle))
+    # Returns the sample rate.
     def sample_rate   = C::Audio.sfSoundBuffer_getSampleRate(@handle)
+    # Returns the channel count.
     def channel_count = C::Audio.sfSoundBuffer_getChannelCount(@handle)
+    # Returns the sample count.
     def sample_count  = C::Audio.sfSoundBuffer_getSampleCount(@handle)
 
     # The decoded 16-bit signed samples as a Ruby Array of

data/lib/sfml/audio/sound_buffer_recorder.rb

@@ -37,6 +37,7 @@ module SFML
       C::Audio.sfSoundBufferRecorder_getChannelCount(@handle)
     end
 
+    # Set the channel count.
     def channel_count=(value)
       C::Audio.sfSoundBufferRecorder_setChannelCount(@handle, Integer(value))
     end
@@ -60,6 +61,7 @@ module SFML
       name unless name.nil? || name.empty?
     end
 
+    # Set the device.
     def device=(name)
       ok = C::Audio.sfSoundBufferRecorder_setDevice(@handle, name.to_s)
       raise AudioError, "could not select recording device #{name.inspect}" unless ok

data/lib/sfml/audio/sound_cone.rb

@@ -28,6 +28,7 @@ module SFML
         outer_gain  == other.outer_gain
     end
     alias eql? ==
+    # Returns the hash.
     def hash = [inner_angle, outer_angle, outer_gain].hash
 
     def to_s

data/lib/sfml/audio/sound_recorder.rb

@@ -113,15 +113,20 @@ module SFML
       self
     end
 
+    # Returns the sample rate.
     def sample_rate   = C::Audio.sfSoundRecorder_getSampleRate(@handle)
+    # Returns the channel count.
     def channel_count = C::Audio.sfSoundRecorder_getChannelCount(@handle)
 
+    # Set the channel count.
     def channel_count=(n)
       C::Audio.sfSoundRecorder_setChannelCount(@handle, Integer(n))
     end
 
+    # Returns the device.
     def device = C::Audio.sfSoundRecorder_getDevice(@handle)
 
+    # Set the device.
     def device=(name)
       C::Audio.sfSoundRecorder_setDevice(@handle, name.to_s) ||
         raise(AudioError, "sfSoundRecorder_setDevice failed for #{name.inspect}")

data/lib/sfml/audio/sound_stream.rb

@@ -94,16 +94,26 @@ module SFML
 
     # ---- Public playback API ------------------------------------------
 
+    # Start streaming. Triggers the audio thread to start polling
+    # `#on_get_data` for chunks. Returns self.
     def play  = (C::Audio.sfSoundStream_play(@handle); self)
+    # Pause streaming. `#play` resumes from here.
     def pause = (C::Audio.sfSoundStream_pause(@handle); self)
+    # Stop streaming and reset internal state.
     def stop  = (C::Audio.sfSoundStream_stop(@handle); self)
 
+    # Playback state — `:stopped`, `:paused`, or `:playing`.
     def status      = C::Audio::STATUSES[C::Audio.sfSoundStream_getStatus(@handle)]
+    # `status == :playing`.
     def playing?    = status == :playing
+    # `status == :paused`.
     def paused?     = status == :paused
+    # `status == :stopped`.
     def stopped?    = status == :stopped
 
+    # Channel count this stream produces (1 = mono, 2 = stereo).
     def channel_count = C::Audio.sfSoundStream_getChannelCount(@handle)
+    # Sample rate in Hz.
     def sample_rate   = C::Audio.sfSoundStream_getSampleRate(@handle)
 
     # Cached on the Ruby side; some OpenAL backends (notably the
@@ -113,37 +123,47 @@ module SFML
       @looping == true
     end
 
+    # Toggle looping playback.
     def looping=(value)
       @looping = !!value
       C::Audio.sfSoundStream_setLooping(@handle, @looping)
     end
 
+    # Playback volume in [0, 100].
     def volume = C::Audio.sfSoundStream_getVolume(@handle)
 
+    # Set the volume.
     def volume=(value)
       C::Audio.sfSoundStream_setVolume(@handle, value.to_f)
     end
 
+    # Pitch multiplier. 1.0 = normal.
     def pitch = C::Audio.sfSoundStream_getPitch(@handle)
 
+    # Set the pitch.
     def pitch=(value)
       C::Audio.sfSoundStream_setPitch(@handle, value.to_f)
     end
 
+    # Current playback head as `SFML::Time`.
     def playing_offset
       Time.from_native(C::Audio.sfSoundStream_getPlayingOffset(@handle))
     end
 
+    # Seek to `value` (`SFML::Time` or numeric seconds). Triggers
+    # `#on_seek` on the subclass.
     def playing_offset=(value)
       t = value.is_a?(Time) ? value : Time.seconds(value.to_f)
       C::Audio.sfSoundStream_setPlayingOffset(@handle, t.to_native)
     end
 
+    # 3D position as a Vector3.
     def position
       v = C::Audio.sfSoundStream_getPosition(@handle)
       Vector3.new(v[:x], v[:y], v[:z])
     end
 
+    # Set the 3D position — accepts Vector3 or `[x, y, z]`.
     def position=(value)
       v = value.is_a?(Vector3) ? value : Vector3.new(*value)
       packed = C::System::Vector3f.new
@@ -151,61 +171,79 @@ module SFML
       C::Audio.sfSoundStream_setPosition(@handle, packed)
     end
 
+    # Falloff sharpness with distance — see `Sound#attenuation`.
     def attenuation = C::Audio.sfSoundStream_getAttenuation(@handle)
 
+    # Set the attenuation.
     def attenuation=(value)
       C::Audio.sfSoundStream_setAttenuation(@handle, value.to_f)
     end
 
+    # Distance below which volume is not attenuated.
     def min_distance = C::Audio.sfSoundStream_getMinDistance(@handle)
 
+    # Set the min-distance.
     def min_distance=(value)
       C::Audio.sfSoundStream_setMinDistance(@handle, value.to_f)
     end
 
+    # `true` if `#position` is interpreted relative to the listener.
     def relative_to_listener? = C::Audio.sfSoundStream_isRelativeToListener(@handle)
 
+    # Toggle listener-relative positioning.
     def relative_to_listener=(value)
       C::Audio.sfSoundStream_setRelativeToListener(@handle, !!value)
     end
 
     # ---- 3D-audio surface (mirror of Sound / Music) -------------------
 
+    # Stereo pan in [-1.0, 1.0].
     def pan = C::Audio.sfSoundStream_getPan(@handle)
 
+    # Set the stereo pan.
     def pan=(value)
       C::Audio.sfSoundStream_setPan(@handle, value.to_f)
     end
 
+    # Distance beyond which the source is fully attenuated.
     def max_distance = C::Audio.sfSoundStream_getMaxDistance(@handle)
 
+    # Set the max-distance.
     def max_distance=(value)
       C::Audio.sfSoundStream_setMaxDistance(@handle, value.to_f)
     end
 
+    # Lower gain bound.
     def min_gain = C::Audio.sfSoundStream_getMinGain(@handle)
 
+    # Set the min-gain floor.
     def min_gain=(value)
       C::Audio.sfSoundStream_setMinGain(@handle, value.to_f)
     end
 
+    # Upper gain bound.
     def max_gain = C::Audio.sfSoundStream_getMaxGain(@handle)
 
+    # Set the max-gain cap.
     def max_gain=(value)
       C::Audio.sfSoundStream_setMaxGain(@handle, value.to_f)
     end
 
+    # `true` if 3D positional / Doppler / cone math is applied.
     def spatialization_enabled? = C::Audio.sfSoundStream_isSpatializationEnabled(@handle)
 
+    # Toggle 3D spatialisation.
     def spatialization_enabled=(value)
       C::Audio.sfSoundStream_setSpatializationEnabled(@handle, !!value)
     end
 
+    # The direction vector for the cone.
     def direction
       v = C::Audio.sfSoundStream_getDirection(@handle)
       Vector3.new(v[:x], v[:y], v[:z])
     end
 
+    # Set the direction — accepts Vector3 or `[x, y, z]`.
     def direction=(value)
       vec = value.is_a?(Vector3) ? value : Vector3.new(*value)
       packed = C::System::Vector3f.new
@@ -213,10 +251,12 @@ module SFML
       C::Audio.sfSoundStream_setDirection(@handle, packed)
     end
 
+    # Directional-attenuation cone.
     def cone
       SoundCone.from_native(C::Audio.sfSoundStream_getCone(@handle))
     end
 
+    # Set the cone. Accepts a `SoundCone` or Hash.
     def cone=(value)
       cone =
         case value
@@ -228,11 +268,13 @@ module SFML
       C::Audio.sfSoundStream_setCone(@handle, cone.to_native)
     end
 
+    # 3D velocity in world units / second.
     def velocity
       v = C::Audio.sfSoundStream_getVelocity(@handle)
       Vector3.new(v[:x], v[:y], v[:z])
     end
 
+    # Set the velocity — accepts Vector3 or `[x, y, z]`.
     def velocity=(value)
       vec = value.is_a?(Vector3) ? value : Vector3.new(*value)
       packed = C::System::Vector3f.new
@@ -240,16 +282,20 @@ module SFML
       C::Audio.sfSoundStream_setVelocity(@handle, packed)
     end
 
+    # Per-source Doppler scale.
     def doppler_factor = C::Audio.sfSoundStream_getDopplerFactor(@handle)
 
+    # Set the Doppler factor.
     def doppler_factor=(value)
       C::Audio.sfSoundStream_setDopplerFactor(@handle, value.to_f)
     end
 
+    # Multiplier on the Listener's directional attenuation cone.
     def directional_attenuation_factor
       C::Audio.sfSoundStream_getDirectionalAttenuationFactor(@handle)
     end
 
+    # Set the directional-attenuation factor.
     def directional_attenuation_factor=(value)
       C::Audio.sfSoundStream_setDirectionalAttenuationFactor(@handle, value.to_f)
     end

data/lib/sfml/graphics/animation.rb

@@ -57,6 +57,7 @@ module SFML
     # meaningful for non-looping animations).
     def done? = @done
 
+    # `true` if playing.
     def playing? = !@done
 
     # Advance by `dt` (a `SFML::Time` or seconds Float). Updates
@@ -107,14 +108,23 @@ module SFML
     # Sprite stays accessible via `#sprite` for advanced cases
     # (color, scale_by, custom blend states, etc.).
     def position    = @sprite.position
+    # Set the position.
     def position=(v); @sprite.position = v; end
+    # Returns the rotation.
     def rotation    = @sprite.rotation
+    # Set the rotation.
     def rotation=(v); @sprite.rotation = v; end
+    # Returns the scale.
     def scale       = @sprite.scale
+    # Set the scale.
     def scale=(v);    @sprite.scale = v; end
+    # Returns the origin.
     def origin      = @sprite.origin
+    # Set the origin.
     def origin=(v);   @sprite.origin = v; end
+    # Returns the color.
     def color       = @sprite.color
+    # Set the color.
     def color=(v);    @sprite.color = v; end
   end
 end

data/lib/sfml/graphics/blend_mode.rb

@@ -47,6 +47,7 @@ module SFML
         alpha_src == other.alpha_src && alpha_dst == other.alpha_dst && alpha_eq == other.alpha_eq
     end
     alias eql? ==
+    # Returns the hash.
     def hash = [color_src, color_dst, color_eq, alpha_src, alpha_dst, alpha_eq].hash
 
     def to_s

data/lib/sfml/graphics/circle_shape.rb

@@ -13,6 +13,10 @@ module SFML
     include Graphics::ShapeInspectable
     CSFML_PREFIX = :sfCircleShape
 
+    # Build a CircleShape. `radius` defaults to 10 px. Any of the
+    # standard styling / transform kwargs can be passed (`fill_color`,
+    # `outline_color`, `outline_thickness`, `texture`, `texture_rect`,
+    # `position`, `origin`, `rotation`, `scale`, `point_count`).
     def initialize(radius: 10.0, **opts)
       ptr = C::Graphics.sfCircleShape_create
       raise GraphicsError, "sfCircleShape_create returned NULL" if ptr.null?
@@ -31,32 +35,44 @@ module SFML
       self.scale              = opts[:scale]              if opts.key?(:scale)
     end
 
+    # Radius in pixels.
     def radius = C::Graphics.sfCircleShape_getRadius(@handle)
 
+    # Set the radius.
     def radius=(value)
       C::Graphics.sfCircleShape_setRadius(@handle, value.to_f)
     end
 
+    # Number of points used to approximate the circle. Default 30
+    # (smooth); set to 3-8 for a regular polygon (triangle, square, ...).
     def point_count = C::Graphics.sfCircleShape_getPointCount(@handle)
 
+    # Set the point count — see `#point_count`.
     def point_count=(n)
       C::Graphics.sfCircleShape_setPointCount(@handle, Integer(n))
     end
 
+    # Interior fill color.
     def fill_color = Color.from_native(C::Graphics.sfCircleShape_getFillColor(@handle))
 
+    # Set the fill color.
     def fill_color=(c)
       C::Graphics.sfCircleShape_setFillColor(@handle, c.to_native)
     end
 
+    # Outline color (only visible when `#outline_thickness > 0`).
     def outline_color = Color.from_native(C::Graphics.sfCircleShape_getOutlineColor(@handle))
 
+    # Set the outline color.
     def outline_color=(c)
       C::Graphics.sfCircleShape_setOutlineColor(@handle, c.to_native)
     end
 
+    # Outline thickness in pixels. Outline is drawn outward by default —
+    # set negative for inward.
     def outline_thickness = C::Graphics.sfCircleShape_getOutlineThickness(@handle)
 
+    # Set the outline thickness.
     def outline_thickness=(t)
       C::Graphics.sfCircleShape_setOutlineThickness(@handle, t.to_f)
     end

data/lib/sfml/graphics/color.rb

@@ -10,6 +10,8 @@ module SFML
   class Color
     attr_reader :r, :g, :b, :a
 
+    # Build a Color from individual channel values. Each must be an
+    # Integer in [0, 255]; alpha defaults to 255 (opaque).
     def initialize(r, g, b, a = 255)
       @r = Integer(r)
       @g = Integer(g)
@@ -18,9 +20,18 @@ module SFML
       freeze
     end
 
+    # Opaque RGB constructor — alias for `.new(r, g, b)`.
     def self.rgb(r, g, b)        = new(r, g, b, 255)
+    # RGBA constructor — alias for `.new(r, g, b, a)`.
     def self.rgba(r, g, b, a)    = new(r, g, b, a)
 
+    # Parse a hex color string. Accepts `#RGB` (each digit doubled),
+    # `#RRGGBB` (opaque), or `#RRGGBBAA` (with alpha). The leading
+    # `#` is optional.
+    #
+    #   SFML::Color["#ff6432"]     #=> Color(255, 100, 50, 255)
+    #   SFML::Color["#ff643280"]   #=> Color(255, 100, 50, 128)
+    #   SFML::Color["#abc"]        #=> Color(170, 187, 204, 255)
     def self.[](hex)
       str = hex.to_s.delete_prefix("#")
       case str.length
@@ -35,17 +46,24 @@ module SFML
       end
     end
 
+    # Value equality — all four channels must match.
     def ==(other)
       other.is_a?(Color) && @r == other.r && @g == other.g && @b == other.b && @a == other.a
     end
     alias eql? ==
+    # Hash key support.
     def hash = [@r, @g, @b, @a].hash
 
+    # `[r, g, b, a]`.
     def to_a = [@r, @g, @b, @a]
+    # `{r:, g:, b:, a:}`.
     def to_h = { r: @r, g: @g, b: @b, a: @a }
+    # Pattern-match support for `in [r, g, b, a]`.
     def deconstruct = to_a
+    # Pattern-match support for `in {r:, g:, b:, a:}`.
     def deconstruct_keys(_keys) = to_h
 
+    # String representation for debugging.
     def to_s = "Color(#{@r}, #{@g}, #{@b}, #{@a})"
     alias inspect to_s
 
@@ -75,6 +93,7 @@ module SFML
       self.class.from_native(C::Graphics.sfColor_add(to_native, other.to_native))
     end
 
+    # Saturating channel-wise subtraction — values clamp at 0.
     def -(other)
       raise ArgumentError, "Color -: expected SFML::Color" unless other.is_a?(Color)
       self.class.from_native(C::Graphics.sfColor_subtract(to_native, other.to_native))
@@ -103,16 +122,28 @@ module SFML
     # A nicer default than pure black for empty windows.
     CORNFLOWER_BLUE = new(100, 149, 237)
 
+    # Convenience accessors for the standard named colors, also
+    # available as `Color::BLACK` etc. for use in constants.
     class << self
+      # Returns the BLACK singleton.
       def black           = BLACK
+      # Returns the WHITE singleton.
       def white           = WHITE
+      # Returns the RED singleton.
       def red             = RED
+      # Returns the GREEN singleton.
       def green           = GREEN
+      # Returns the BLUE singleton.
       def blue            = BLUE
+      # Returns the YELLOW singleton.
       def yellow          = YELLOW
+      # Returns the MAGENTA singleton.
       def magenta         = MAGENTA
+      # Returns the CYAN singleton.
       def cyan            = CYAN
+      # Returns the TRANSPARENT singleton (alpha = 0).
       def transparent     = TRANSPARENT
+      # Returns the CORNFLOWER_BLUE singleton — handy default for empty windows.
       def cornflower_blue = CORNFLOWER_BLUE
     end
   end

data/lib/sfml/graphics/convex_shape.rb

@@ -16,6 +16,8 @@ module SFML
     include Graphics::ShapeInspectable
     CSFML_PREFIX = :sfConvexShape
 
+    # Build a ConvexShape. `points:` may be passed up-front (Array of
+    # `[x, y]` / Vector2) or omitted and set later via `#points=`.
     def initialize(points: nil, **opts)
       ptr = C::Graphics.sfConvexShape_create
       raise GraphicsError, "sfConvexShape_create returned NULL" if ptr.null?
@@ -33,6 +35,7 @@ module SFML
       self.scale             = opts[:scale]             if opts.key?(:scale)
     end
 
+    # Number of polygon vertices currently set.
     def point_count = C::Graphics.sfConvexShape_getPointCount(@handle)
 
     # Returns the polygon vertices as an Array of Vector2.
@@ -58,20 +61,26 @@ module SFML
       C::Graphics.sfConvexShape_setPoint(@handle, Integer(index), vec.to_native_f)
     end
 
+    # Interior fill color.
     def fill_color = Color.from_native(C::Graphics.sfConvexShape_getFillColor(@handle))
 
+    # Set the fill color.
     def fill_color=(c)
       C::Graphics.sfConvexShape_setFillColor(@handle, c.to_native)
     end
 
+    # Outline color (only visible when `#outline_thickness > 0`).
     def outline_color = Color.from_native(C::Graphics.sfConvexShape_getOutlineColor(@handle))
 
+    # Set the outline color.
     def outline_color=(c)
       C::Graphics.sfConvexShape_setOutlineColor(@handle, c.to_native)
     end
 
+    # Outline thickness in pixels — negative draws inward.
     def outline_thickness = C::Graphics.sfConvexShape_getOutlineThickness(@handle)
 
+    # Set the outline thickness.
     def outline_thickness=(t)
       C::Graphics.sfConvexShape_setOutlineThickness(@handle, t.to_f)
     end

data/lib/sfml/graphics/font.rb

@@ -86,8 +86,10 @@ module SFML
       nil
     end
 
+    # `true` if smooth.
     def smooth?       = C::Graphics.sfFont_isSmooth(@handle)
 
+    # Set the smooth.
     def smooth=(value)
       C::Graphics.sfFont_setSmooth(@handle, !!value)
     end

data/lib/sfml/graphics/image.rb

@@ -94,7 +94,9 @@ module SFML
       Vector2.from_native(C::Graphics.sfImage_getSize(@handle))
     end
 
+    # Returns the width.
     def width  = size.x
+    # Returns the height.
     def height = size.y
 
     # Read the colour of a single pixel.