Add YARD documentation and inline RBS type signatures

Author: joshuay03

CHANGELOG.md

@@ -1,5 +1,7 @@
 ## [Unreleased]
 
+- Add YARD documentation and inline RBS type signatures
+
 ## [0.9.0] - 2025-11-05
 
 - Switch `AtomicThreadPool` back to atomics now that Ractor safety is lazy

Gemfile

@@ -11,6 +11,10 @@ gem "rake-compiler"
 
 gem "minitest"
 
+gem "rbs-inline"
+
+gem "yard"
+
 gem "debug"
 
 gem "benchmark"

lib/atomic-ruby/atom.rb

@@ -1,17 +1,94 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
 require "atomic_ruby/atomic_ruby"
 
 module AtomicRuby
+  # Provides atomic reference semantics using Compare-And-Swap (CAS) operations.
+  #
+  # An Atom allows for lock-free, thread-safe updates to a single reference value.
+  # The core operation is {#swap}, which atomically updates the value based on
+  # the current value, retrying if another thread modifies it concurrently.
+  #
+  # @example Basic usage
+  #   atom = Atom.new(0)
+  #   atom.swap { |current_value| current_value + 1 }
+  #   puts atom.value #=> 1
+  #
+  # @example Thread-safe counter
+  #   counter = Atom.new(0)
+  #   threads = 10.times.map do
+  #     Thread.new { 100.times { counter.swap { |current_count| current_count + 1 } } }
+  #   end
+  #   threads.each(&:join)
+  #   puts counter.value #=> 1000
+  #
+  # @example Non-mutating array operations
+  #   atom = Atom.new([])
+  #   atom.swap { |current_array| current_array + [1] }
+  #   atom.swap { |current_array| current_array + [2] }
+  #   puts atom.value #=> [1, 2]
+  #
+  # @note This class is Ractor-safe in Ruby 4.0+ when compiled with ractor support.
+  #   Values that cross ractor boundaries are automatically made shareable.
   class Atom
+    # Creates a new atomic reference with the given initial value.
+    #
+    # @param value [untyped] The initial value to store atomically
+    #
+    # @example
+    #   atom = Atom.new(42)
+    #   atom = Atom.new([1, 2, 3])
+    #   atom = Atom.new({ key: "value" })
+    #
+    # @rbs (untyped value) -> void
     def initialize(value)
       _initialize(value)
     end
 
+    # Returns the current value stored in the atom.
+    #
+    # This operation is atomic and thread-safe. The returned value reflects
+    # the state at the time of the call, but may change immediately after
+    # in concurrent environments.
+    #
+    # @return [untyped] The current atomic value
+    #
+    # @example
+    #   atom = Atom.new("hello")
+    #   puts atom.value #=> "hello"
+    #
+    # @rbs () -> untyped
     def value
       _value
     end
 
+    # Atomically updates the value using a compare-and-swap operation.
+    #
+    # The block receives the current value and must return the new value.
+    # If another thread modifies the atom between reading the current value
+    # and attempting to update it, the operation retries with the new current value.
+    #
+    # @yieldparam current_value [untyped] The current atomic value
+    # @yieldreturn [untyped] The new value to store atomically
+    # @return [untyped] The new value that was successfully stored
+    #
+    # @example Increment a counter
+    #   atom = Atom.new(0)
+    #   new_value = atom.swap { |current_value| current_value + 1 }
+    #   puts new_value #=> 1
+    #
+    # @example Append to array (non-mutating)
+    #   atom = Atom.new([1, 2])
+    #   atom.swap { |current_array| current_array + [3] }
+    #   puts atom.value #=> [1, 2, 3]
+    #
+    # @example Conditional update
+    #   atom = Atom.new(10)
+    #   atom.swap { |current_value| current_value > 5 ? current_value * 2 : current_value }
+    #   puts atom.value #=> 20
+    #
+    # @rbs () { (untyped) -> untyped } -> untyped
     def swap(&block)
       _swap do |old_value|
         make_shareable_if_needed(block.call(old_value))
@@ -20,6 +97,15 @@ def swap(&block)
 
     private
 
+    # Makes a value shareable when crossing ractor boundaries.
+    #
+    # This method ensures ractor safety by automatically making values
+    # shareable when they need to cross ractor boundaries in Ruby 4.0+.
+    #
+    # @param value [untyped] The value to potentially make shareable
+    # @return [untyped] The original value or shareable version
+    #
+    # @rbs (untyped value) -> untyped
     def make_shareable_if_needed(value)
       if RACTOR_SAFE &&
          (_initialized_ractor.nil? || Ractor.current != _initialized_ractor)

lib/atomic-ruby/atomic_boolean.rb

@@ -1,9 +1,50 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
 require_relative "atom"
 
 module AtomicRuby
+  # Provides atomic boolean semantics with thread-safe toggle operations.
+  #
+  # AtomicBoolean wraps a boolean value in an atomic reference, providing
+  # lock-free operations for common boolean manipulations like toggling,
+  # setting to true/false, and checking the current state.
+  #
+  # @example Basic usage
+  #   boolean = AtomicBoolean.new(false)
+  #   puts boolean.false? #=> true
+  #   boolean.toggle
+  #   puts boolean.true?  #=> true
+  #
+  # @example Thread-safe toggle
+  #   boolean = AtomicBoolean.new(false)
+  #   threads = 10.times.map do
+  #     Thread.new { 100.times { boolean.toggle } }
+  #   end
+  #   threads.each(&:join)
+  #   # Final state depends on whether total toggles is even or odd
+  #
+  # @example Atomic flag setting
+  #   flag = AtomicBoolean.new(false)
+  #   flag.make_true
+  #   puts flag.value #=> true
+  #
+  # @note This class is Ractor-safe in Ruby 4.0+ when compiled with ractor support.
   class AtomicBoolean
+    # Creates a new atomic boolean with the given initial value.
+    #
+    # @param boolean [true, false] The initial boolean value
+    # @raise [ArgumentError] if the value is not a boolean (TrueClass or FalseClass)
+    #
+    # @example
+    #   boolean = AtomicBoolean.new(true)
+    #   boolean = AtomicBoolean.new(false)
+    #
+    # @example Invalid usage
+    #   AtomicBoolean.new(nil)     #=> raises ArgumentError
+    #   AtomicBoolean.new("true")  #=> raises ArgumentError
+    #
+    # @rbs (bool boolean) -> void
     def initialize(boolean)
       unless boolean.is_a?(TrueClass) || boolean.is_a?(FalseClass)
         raise ArgumentError, "boolean must be a TrueClass or FalseClass"
@@ -14,26 +55,102 @@ def initialize(boolean)
       Ractor.make_shareable(self) if RACTOR_SAFE
     end
 
+    # Returns the current boolean value stored in the atom.
+    #
+    # This operation is atomic and thread-safe. The returned value reflects
+    # the state at the time of the call, but may change immediately after
+    # in concurrent environments.
+    #
+    # @return [true, false] The current atomic boolean value
+    #
+    # @example
+    #   boolean = AtomicBoolean.new(true)
+    #   puts boolean.value #=> true
+    #
+    # @rbs () -> bool
     def value
       @boolean.value
     end
 
+    # Tests if the current value is true.
+    #
+    # @return [true, false] true if the atomic value is true, false otherwise
+    #
+    # @example
+    #   boolean = AtomicBoolean.new(true)
+    #   puts boolean.true?  #=> true
+    #   puts boolean.false? #=> false
+    #
+    # @rbs () -> bool
     def true?
       value == true
     end
 
+    # Tests if the current value is false.
+    #
+    # @return [true, false] true if the atomic value is false, false otherwise
+    #
+    # @example
+    #   boolean = AtomicBoolean.new(false)
+    #   puts boolean.false? #=> true
+    #   puts boolean.true?  #=> false
+    #
+    # @rbs () -> bool
     def false?
       value == false
     end
 
+    # Atomically sets the value to true.
+    #
+    # This operation uses compare-and-swap to ensure atomicity,
+    # making it safe for concurrent access.
+    #
+    # @return [true] Always returns true (the new value)
+    #
+    # @example
+    #   boolean = AtomicBoolean.new(false)
+    #   boolean.make_true
+    #   puts boolean.value #=> true
+    #
+    # @rbs () -> true
     def make_true
       @boolean.swap { true }
     end
 
+    # Atomically sets the value to false.
+    #
+    # This operation uses compare-and-swap to ensure atomicity,
+    # making it safe for concurrent access.
+    #
+    # @return [false] Always returns false (the new value)
+    #
+    # @example
+    #   boolean = AtomicBoolean.new(true)
+    #   boolean.make_false
+    #   puts boolean.value #=> false
+    #
+    # @rbs () -> false
     def make_false
       @boolean.swap { false }
     end
 
+    # Atomically toggles the boolean value.
+    #
+    # Changes true to false and false to true using a compare-and-swap
+    # operation, making it safe for concurrent access from multiple threads.
+    #
+    # @return [true, false] The new boolean value after toggling
+    #
+    # @example
+    #   boolean = AtomicBoolean.new(false)
+    #   boolean.toggle #=> true
+    #   boolean.toggle #=> false
+    #
+    # @example Thread-safe toggling
+    #   boolean = AtomicBoolean.new(false)
+    #   10.times.map { Thread.new { boolean.toggle } }.each(&:join)
+    #
+    # @rbs () -> bool
     def toggle
       @boolean.swap { |current_value| !current_value }
     end