ruby-sfml 3.0.0.6 → 3.0.0.7

data/lib/sfml/network/ftp.rb

@@ -45,6 +45,8 @@ module SFML
         1002 => :connection_closed, 1003 => :invalid_file,
       }.freeze
 
+      # Create a new FTP client. Call `#connect` next to open a
+      # session.
       def initialize
         ptr = C::Network.sfFtp_create
         raise NetworkError, "sfFtp_create returned NULL" if ptr.null?
@@ -61,61 +63,78 @@ module SFML
         Response._take_ownership(C::Network.sfFtp_connect(@handle, addr, Integer(port), t.to_native))
       end
 
+      # Log in as anonymous. Returns a `Response`.
       def login_anonymous
         Response._take_ownership(C::Network.sfFtp_loginAnonymous(@handle))
       end
 
+      # Log in with credentials.
       def login(user, password)
         Response._take_ownership(C::Network.sfFtp_login(@handle, user.to_s, password.to_s))
       end
 
+      # Close the connection.
       def disconnect = Response._take_ownership(C::Network.sfFtp_disconnect(@handle))
+      # Send a no-op to keep the connection alive against server timeouts.
       def keep_alive = Response._take_ownership(C::Network.sfFtp_keepAlive(@handle))
 
+      # Current working directory as a `DirectoryResponse`.
       def working_directory
         DirectoryResponse._take_ownership(C::Network.sfFtp_getWorkingDirectory(@handle))
       end
 
+      # List `directory` (default = current). Returns a `ListingResponse`.
       def directory_listing(directory = "")
         ListingResponse._take_ownership(C::Network.sfFtp_getDirectoryListing(@handle, directory.to_s))
       end
 
+      # `cd` to a directory.
       def change_directory(directory)
         Response._take_ownership(C::Network.sfFtp_changeDirectory(@handle, directory.to_s))
       end
 
+      # `cd ..`.
       def parent_directory
         Response._take_ownership(C::Network.sfFtp_parentDirectory(@handle))
       end
 
+      # `mkdir` — returns a `DirectoryResponse` with the new path.
       def create_directory(name)
         DirectoryResponse._take_ownership(C::Network.sfFtp_createDirectory(@handle, name.to_s))
       end
 
+      # `rmdir`.
       def delete_directory(name)
         Response._take_ownership(C::Network.sfFtp_deleteDirectory(@handle, name.to_s))
       end
 
+      # Rename / move a file on the server.
       def rename_file(file, new_name)
         Response._take_ownership(C::Network.sfFtp_renameFile(@handle, file.to_s, new_name.to_s))
       end
 
+      # Delete a single file.
       def delete_file(name)
         Response._take_ownership(C::Network.sfFtp_deleteFile(@handle, name.to_s))
       end
 
+      # Pull `remote` from the server to local path. `mode` is
+      # `:binary` (default), `:ascii`, or `:ebcdic`.
       def download(remote, local, mode: :binary)
         idx = C::Network::FTP_TRANSFER_MODES.index(mode) ||
           raise(ArgumentError, "Unknown FTP transfer mode: #{mode.inspect}")
         Response._take_ownership(C::Network.sfFtp_download(@handle, remote.to_s, local.to_s, idx))
       end
 
+      # Push `local` to `remote`. `append: true` extends an existing
+      # remote file rather than replacing it.
       def upload(local, remote, mode: :binary, append: false)
         idx = C::Network::FTP_TRANSFER_MODES.index(mode) ||
           raise(ArgumentError, "Unknown FTP transfer mode: #{mode.inspect}")
         Response._take_ownership(C::Network.sfFtp_upload(@handle, local.to_s, remote.to_s, idx, !!append))
       end
 
+      # Send a raw FTP command (e.g. "STAT") and an optional parameter.
       def send_command(command, parameter = "")
         Response._take_ownership(C::Network.sfFtp_sendCommand(@handle, command.to_s, parameter.to_s))
       end
@@ -124,9 +143,13 @@ module SFML
 
       # Generic response: most FTP operations return this.
       class Response
+        # `true` if ok.
         def ok?           = C::Network.sfFtpResponse_isOk(@handle)
+        # Returns the status.
         def status        = C::Network.sfFtpResponse_getStatus(@handle)
+        # Returns the status symbol.
         def status_symbol = STATUS_NAMES[status] || status
+        # Returns the message.
         def message       = C::Network.sfFtpResponse_getMessage(@handle).to_s
         attr_reader :handle # :nodoc:
 
@@ -142,10 +165,15 @@ module SFML
       # Returned by working_directory and create_directory — adds the
       # `#directory` accessor on top of Response.
       class DirectoryResponse
+        # `true` if ok.
         def ok?           = C::Network.sfFtpDirectoryResponse_isOk(@handle)
+        # Returns the status.
         def status        = C::Network.sfFtpDirectoryResponse_getStatus(@handle)
+        # Returns the status symbol.
         def status_symbol = STATUS_NAMES[status] || status
+        # Returns the message.
         def message       = C::Network.sfFtpDirectoryResponse_getMessage(@handle).to_s
+        # Returns the directory.
         def directory     = C::Network.sfFtpDirectoryResponse_getDirectory(@handle).to_s
         attr_reader :handle # :nodoc:
 
@@ -160,13 +188,19 @@ module SFML
 
       # Returned by directory_listing — adds the `#names` array.
       class ListingResponse
+        # `true` if ok.
         def ok?           = C::Network.sfFtpListingResponse_isOk(@handle)
+        # Returns the status.
         def status        = C::Network.sfFtpListingResponse_getStatus(@handle)
+        # Returns the status symbol.
         def status_symbol = STATUS_NAMES[status] || status
+        # Returns the message.
         def message       = C::Network.sfFtpListingResponse_getMessage(@handle).to_s
+        # Returns the count.
         def count         = C::Network.sfFtpListingResponse_getCount(@handle)
         attr_reader :handle # :nodoc:
 
+        # Filenames returned by the listing, as an Array of Strings.
         def names
           Array.new(count) { |i| C::Network.sfFtpListingResponse_getName(@handle, i).to_s }
         end

data/lib/sfml/network/http.rb

@@ -92,6 +92,7 @@ module SFML
           STATUS_NAMES[status] || status
         end
 
+        # Returns the body.
         def body  = C::Network.sfHttpResponse_getBody(@handle).to_s
         def field(name) = C::Network.sfHttpResponse_getField(@handle, name.to_s)
 

data/lib/sfml/network/ip_address.rb

@@ -53,6 +53,7 @@ module SFML
         other.is_a?(IpAddress) && to_s == other.to_s
       end
       alias eql? ==
+      # Returns the hash.
       def hash = to_s.hash
 
       # @!visibility private

data/lib/sfml/network/packet.rb

@@ -52,8 +52,11 @@ module SFML
         ptr.read_bytes(size).force_encoding(Encoding::ASCII_8BIT)
       end
 
+      # Returns the size.
       def size            = C::Network.sfPacket_getDataSize(@handle)
+      # Returns the read position.
       def read_position   = C::Network.sfPacket_getReadPosition(@handle)
+      # `true` if end of packet.
       def end_of_packet?  = C::Network.sfPacket_endOfPacket(@handle)
 
       # `false` if the last read overran the packet — sfPacket "fails"
@@ -62,20 +65,35 @@ module SFML
       def ok? = C::Network.sfPacket_canRead(@handle)
 
       # ---- typed writers ----
+      # All writers append to the end of the packet and return self
+      # for chaining.
+
+      # Append a Bool.
       def write_bool(v)
         C::Network.sfPacket_writeBool(@handle, v ? true : false); self
       end
+      # Append a signed 8-bit Integer.
       def write_int8(v)   = (C::Network.sfPacket_writeInt8(@handle,   Integer(v)); self)
+      # Append an unsigned 8-bit Integer.
       def write_uint8(v)  = (C::Network.sfPacket_writeUint8(@handle,  Integer(v)); self)
+      # Append a signed 16-bit Integer.
       def write_int16(v)  = (C::Network.sfPacket_writeInt16(@handle,  Integer(v)); self)
+      # Append an unsigned 16-bit Integer.
       def write_uint16(v) = (C::Network.sfPacket_writeUint16(@handle, Integer(v)); self)
+      # Append a signed 32-bit Integer.
       def write_int32(v)  = (C::Network.sfPacket_writeInt32(@handle,  Integer(v)); self)
+      # Append an unsigned 32-bit Integer.
       def write_uint32(v) = (C::Network.sfPacket_writeUint32(@handle, Integer(v)); self)
+      # Append a signed 64-bit Integer.
       def write_int64(v)  = (C::Network.sfPacket_writeInt64(@handle,  Integer(v)); self)
+      # Append an unsigned 64-bit Integer.
       def write_uint64(v) = (C::Network.sfPacket_writeUint64(@handle, Integer(v)); self)
+      # Append a single-precision Float.
       def write_float(v)  = (C::Network.sfPacket_writeFloat(@handle,  Float(v));   self)
+      # Append a double-precision Float.
       def write_double(v) = (C::Network.sfPacket_writeDouble(@handle, Float(v));   self)
 
+      # Append a length-prefixed UTF-8 String.
       def write_string(str)
         C::Network.sfPacket_writeString(@handle, str.to_s)
         self
@@ -83,15 +101,25 @@ module SFML
 
       # ---- typed readers ----
       def read_bool   = C::Network.sfPacket_readBool(@handle)
+      # Returns the read int8.
       def read_int8   = C::Network.sfPacket_readInt8(@handle)
+      # Returns the read uint8.
       def read_uint8  = C::Network.sfPacket_readUint8(@handle)
+      # Returns the read int16.
       def read_int16  = C::Network.sfPacket_readInt16(@handle)
+      # Returns the read uint16.
       def read_uint16 = C::Network.sfPacket_readUint16(@handle)
+      # Returns the read int32.
       def read_int32  = C::Network.sfPacket_readInt32(@handle)
+      # Returns the read uint32.
       def read_uint32 = C::Network.sfPacket_readUint32(@handle)
+      # Returns the read int64.
       def read_int64  = C::Network.sfPacket_readInt64(@handle)
+      # Returns the read uint64.
       def read_uint64 = C::Network.sfPacket_readUint64(@handle)
+      # Returns the read float.
       def read_float  = C::Network.sfPacket_readFloat(@handle)
+      # Returns the read double.
       def read_double = C::Network.sfPacket_readDouble(@handle)
 
       # Read a length-prefixed string. CSFML expects a caller-allocated

data/lib/sfml/network/socket_selector.rb

@@ -76,6 +76,7 @@ module SFML
         C::Network.sfSocketSelector_wait(@handle, t.to_native)
       end
 
+      # `true` if ready.
       def ready?(socket)
         case socket
         when TcpListener then C::Network.sfSocketSelector_isTcpListenerReady(@handle, socket.handle)

data/lib/sfml/network/tcp_listener.rb

@@ -47,12 +47,15 @@ module SFML
         [status, sock]
       end
 
+      # `true` if blocking.
       def blocking? = C::Network.sfTcpListener_isBlocking(@handle)
 
+      # Set the blocking.
       def blocking=(value)
         C::Network.sfTcpListener_setBlocking(@handle, value ? true : false)
       end
 
+      # Returns the local port.
       def local_port = C::Network.sfTcpListener_getLocalPort(@handle)
 
       attr_reader :handle # :nodoc:

data/lib/sfml/network/tcp_socket.rb

@@ -74,13 +74,17 @@ module SFML
         [status, status == :done ? pkt : nil]
       end
 
+      # `true` if blocking.
       def blocking? = C::Network.sfTcpSocket_isBlocking(@handle)
 
+      # Set the blocking.
       def blocking=(value)
         C::Network.sfTcpSocket_setBlocking(@handle, value ? true : false)
       end
 
+      # Returns the local port.
       def local_port  = C::Network.sfTcpSocket_getLocalPort(@handle)
+      # Returns the remote port.
       def remote_port = C::Network.sfTcpSocket_getRemotePort(@handle)
 
       def remote_address

data/lib/sfml/network/udp_socket.rb

@@ -80,12 +80,15 @@ module SFML
         [status, pkt, IpAddress.wrap(sender_addr), sender_port.read(:uint16)]
       end
 
+      # `true` if blocking.
       def blocking? = C::Network.sfUdpSocket_isBlocking(@handle)
 
+      # Set the blocking.
       def blocking=(value)
         C::Network.sfUdpSocket_setBlocking(@handle, value ? true : false)
       end
 
+      # Returns the local port.
       def local_port = C::Network.sfUdpSocket_getLocalPort(@handle)
 
       attr_reader :handle # :nodoc:

data/lib/sfml/scene.rb

@@ -48,7 +48,9 @@ module SFML
 
     # Convenience accessors that match `SFML::App`'s.
     def window = @app.window
+    # Returns the width.
     def width  = @app.width
+    # Returns the height.
     def height = @app.height
 
     # Switch the host app to a new scene from inside this one.

data/lib/sfml/system/clock.rb

@@ -17,6 +17,7 @@ module SFML
     end
     alias elapsed elapsed_time
 
+    # `true` if running.
     def running?
       C::System.sfClock_isRunning(@handle)
     end

data/lib/sfml/system/rect.rb

@@ -1,9 +1,9 @@
 module SFML
-  # An axis-aligned rectangle. Mirrors sfFloatRect / sfIntRect — those structs
-  # are just (position: Vector2, size: Vector2). We deliberately keep one
-  # Ruby class for both the float and int variants since pattern-matching
-  # `case bounds in {position: {x:, y:}, size: {x: w, y: h}}` is what the
-  # users reach for either way.
+  # An axis-aligned rectangle. Mirrors sfFloatRect / sfIntRect — those
+  # structs are just `(position: Vector2, size: Vector2)`. We
+  # deliberately keep one Ruby class for both the float and int
+  # variants since pattern-matching `case bounds in {position: {x:,
+  # y:}, size: {x: w, y: h}}` is what users reach for either way.
   #
   #   r = SFML::Rect.new([10, 20], [100, 50])
   #   r.contains?([50, 30])    #=> true
@@ -13,26 +13,38 @@ module SFML
   class Rect
     attr_reader :position, :size
 
+    # `position` and `size` may each be a `Vector2` OR a `[x, y]` Array.
     def initialize(position, size)
       @position = position.is_a?(Vector2) ? position : Vector2.new(*position)
       @size     = size.is_a?(Vector2) ? size : Vector2.new(*size)
       freeze
     end
 
+    # Top-left X.
     def x      = @position.x
+    # Top-left Y.
     def y      = @position.y
+    # Width.
     def width  = @size.x
+    # Height.
     def height = @size.y
     alias left x
     alias top  y
+
+    # X of the right edge (`x + width`).
     def right  = @position.x + @size.x
+    # Y of the bottom edge (`y + height`).
     def bottom = @position.y + @size.y
 
+    # `true` if `point` (Vector2 or `[x, y]`) is inside this rect.
+    # The right and bottom edges are exclusive.
     def contains?(point)
       px, py = point.is_a?(Vector2) ? [point.x, point.y] : [point[0], point[1]]
       px >= left && px < right && py >= top && py < bottom
     end
 
+    # `true` if this rect overlaps `other` at all (any non-empty
+    # intersection counts).
     def intersects?(other)
       left   < other.right  &&
         right  > other.left  &&
@@ -40,17 +52,27 @@ module SFML
         bottom > other.top
     end
 
+    # Value equality — same position + same size.
     def ==(other)
       other.is_a?(Rect) && @position == other.position && @size == other.size
     end
     alias eql? ==
+    # Hash key support.
     def hash = [@position, @size].hash
 
+    # `[x, y, width, height]`.
     def to_a = [x, y, width, height]
+
+    # `{position:, size:}`.
     def to_h = { position: @position, size: @size }
+
+    # Pattern-match support for `in [x, y, w, h]`.
     def deconstruct = [x, y, width, height]
+
+    # Pattern-match support for `in {position:, size:}`.
     def deconstruct_keys(_keys) = { position: @position, size: @size }
 
+    # String representation for debugging.
     def to_s = "Rect(x=#{x}, y=#{y}, w=#{width}, h=#{height})"
     alias inspect to_s
 

data/lib/sfml/system/time.rb

@@ -1,19 +1,27 @@
 module SFML
-  # Represents a time value. Stored internally as microseconds (int64), same
-  # as sfTime in CSFML. Immutable and comparable.
+  # Represents a time value. Stored internally as microseconds (int64),
+  # same as `sfTime` in CSFML. Immutable and Comparable, so two Times
+  # can be `==` / `<` / `>` / sorted.
   #
   #   SFML::Time.seconds(1.5)        #=> 1_500_000 µs
   #   SFML::Time.milliseconds(500)
   #   SFML::Time.microseconds(42)
   #   SFML::Time.zero
+  #
+  #   t1 + t2                        # sum of two Times
+  #   t.as_seconds                   # Float seconds
   class Time
     include Comparable
 
     attr_reader :microseconds
 
+    # Build a Time from a Float of seconds.
     def self.seconds(value)      = new((value * 1_000_000).to_i)
+    # Build a Time from an Integer of milliseconds.
     def self.milliseconds(value) = new(Integer(value) * 1_000)
+    # Build a Time directly from microseconds.
     def self.microseconds(value) = new(Integer(value))
+    # The zero Time.
     def self.zero                = new(0)
 
     def initialize(microseconds)
@@ -21,19 +29,31 @@ module SFML
       freeze
     end
 
+    # As Float seconds.
     def as_seconds      = @microseconds / 1_000_000.0
+    # As Integer milliseconds (truncated).
     def as_milliseconds = @microseconds / 1_000
+    # As Integer microseconds — the raw stored value.
     def as_microseconds = @microseconds
 
+    # Sum of two Times — returns a fresh Time.
     def +(other) = Time.new(@microseconds + other.microseconds)
+    # Difference between two Times.
     def -(other) = Time.new(@microseconds - other.microseconds)
+    # Negate (useful when computing a "ago" offset).
     def -@       = Time.new(-@microseconds)
+
+    # Compare two Times — implements `Comparable`, so `<`, `<=`, `>=`,
+    # `>`, `clamp`, and `Array#sort` all work.
     def <=>(other) = @microseconds <=> other.microseconds
 
+    # Hash key support — Times can be Hash keys / Set members.
     def hash = @microseconds.hash
+    # Value equality.
     def eql?(other) = other.is_a?(Time) && @microseconds == other.microseconds
     alias == eql?
 
+    # String representation for debugging.
     def to_s = "#<SFML::Time #{as_seconds}s>"
     alias inspect to_s
 

data/lib/sfml/system/vector2.rb

@@ -9,8 +9,12 @@ module SFML
   class Vector2
     attr_reader :x, :y
 
+    # Compact constructor: `Vector2[3, 4]` reads naturally as a literal.
     def self.[](x, y) = new(x, y)
-    def self.zero     = new(0, 0)
+
+    # The (0, 0) vector. Reused as a singleton-style fallback (e.g.
+    # `#normalize` returns this for the zero vector).
+    def self.zero = new(0, 0)
 
     def initialize(x = 0, y = 0)
       @x = x
@@ -18,10 +22,15 @@ module SFML
       freeze
     end
 
+    # Component-wise addition.
     def +(other) = Vector2.new(@x + other.x, @y + other.y)
+    # Component-wise subtraction.
     def -(other) = Vector2.new(@x - other.x, @y - other.y)
+    # Multiply both components by `scalar`.
     def *(scalar) = Vector2.new(@x * scalar, @y * scalar)
+    # Divide both components by `scalar`. Always promotes to Float.
     def /(scalar) = Vector2.new(@x / scalar.to_f, @y / scalar.to_f)
+    # Negate both components.
     def -@ = Vector2.new(-@x, -@y)
 
     # Lets Ruby evaluate `2 * vec` as `vec * 2`. Without this, Numeric#*
@@ -31,24 +40,40 @@ module SFML
       [self, other]
     end
 
+    # Value equality — two Vector2s are equal when both components match.
     def ==(other) = other.is_a?(Vector2) && @x == other.x && @y == other.y
     alias eql? ==
+    # Hash key support — Vector2s can be Hash keys / Set members.
     def hash = [@x, @y].hash
 
+    # Euclidean length √(x² + y²). For comparisons prefer `length_sq` —
+    # avoids the square root.
     def length    = Math.sqrt(length_sq)
+    # Squared length (x² + y²) — comparisons can use this without the
+    # `sqrt` call.
     def length_sq = (@x * @x) + (@y * @y)
 
+    # Unit vector pointing the same way as `self`. Returns the zero
+    # vector unchanged (no division by zero).
     def normalize
       len = length
       return Vector2.zero if len.zero?
       self / len
     end
 
+    # Scalar dot product. Positive when both vectors point roughly the
+    # same way, negative when opposite, zero when perpendicular.
     def dot(other)   = (@x * other.x) + (@y * other.y)
+
+    # Scalar 2D cross product (a.k.a. perpendicular dot). Positive when
+    # `other` is counter-clockwise from `self`, negative when clockwise.
     def cross(other) = (@x * other.y) - (@y * other.x)
 
-    # Euclidean distance between two points.
+    # Euclidean distance to `other` — accepts a Vector2 or `[x, y]`.
     def distance(other)    = (self - _coerce(other)).length
+
+    # Squared distance to `other` — skip the `sqrt` if you only need to
+    # compare two distances.
     def distance_sq(other) = (self - _coerce(other)).length_sq
 
     # Angle of this vector relative to +X axis, in radians (-π..π].
@@ -64,6 +89,7 @@ module SFML
     # if you already have radians.
     def rotated(degrees) = rotated_rad(degrees * Math::PI / 180.0)
 
+    # Vector rotated by `radians` counter-clockwise.
     def rotated_rad(radians)
       c, s = Math.cos(radians), Math.sin(radians)
       Vector2.new(@x * c - @y * s, @x * s + @y * c)
@@ -109,15 +135,29 @@ module SFML
       self * (target / len)
     end
 
+    # `true` iff both components are zero.
     def zero?  = @x.zero? && @y.zero?
+
+    # Per-component absolute value.
     def abs    = Vector2.new(@x.abs, @y.abs)
+
+    # Promote to a Vector3 with optional `z` (default 0).
     def to_v3(z = 0.0) = Vector3.new(@x, @y, z)
 
+    # As a 2-element `[x, y]` Array — supports splat destructuring:
+    # `x, y = vec`.
     def to_a = [@x, @y]
+
+    # As a `{x:, y:}` Hash.
     def to_h = { x: @x, y: @y }
+
+    # Pattern-match support for `in [x, y]`.
     def deconstruct = [@x, @y]
+
+    # Pattern-match support for `in {x:, y:}`.
     def deconstruct_keys(_keys) = { x: @x, y: @y }
 
+    # String representation for debugging.
     def to_s = "Vector2(#{@x}, #{@y})"
     alias inspect to_s