RBS Annotate

Add inline RBS type annotations directly to Ruby source code using magic comments.

Instructions

1. Inline Annotation Formats

RBS supports inline annotations via magic comments:

# @rbs generic T
class Container
  # @rbs @items: Array[T]

  # @rbs (T item) -> void
  def add(item)
    @items << item
  end

  # @rbs () -> T?
  def first
    @items.first
  end
end

2. Method Annotations

Basic method signature:

# @rbs (String name, Integer age) -> User
def create_user(name, age)
  User.new(name, age)
end

Optional parameters:

# @rbs (String name, ?Integer age) -> User
def create_user(name, age = nil)
  User.new(name, age)
end

Keyword arguments:

# @rbs (name: String, age: Integer) -> User
def create_user(name:, age:)
  User.new(name, age)
end

Block parameters:

# @rbs (Array[String] items) { (String) -> void } -> void
def process(items, &block)
  items.each(&block)
end

Splat arguments:

# @rbs (*String names) -> Array[User]
def create_users(*names)
  names.map { |n| User.new(n) }
end

3. Instance Variable Annotations

class User
  # @rbs @name: String
  # @rbs @email: String
  # @rbs @active: bool

  def initialize(name, email)
    @name = name
    @email = email
    @active = true
  end
end

4. Attribute Annotations

class User
  # @rbs!
  #   attr_reader name: String
  #   attr_reader email: String
  #   attr_accessor active: bool

  attr_reader :name, :email
  attr_accessor :active
end

5. Class-Level Annotations

Generic classes:

# @rbs generic T
class Stack
  # @rbs @items: Array[T]

  # @rbs (T item) -> void
  def push(item)
    @items.push(item)
  end
end

Module inclusion:

# @rbs!
#   include Enumerable[User]
class UserCollection
  include Enumerable
end

6. Annotation Guidelines

When to use inline annotations:

• Small files with few types
• Prototyping before separate RBS files
• Documentation-heavy code
• Keeping types close to implementation

Best practices:

• Keep annotations concise
• Use type aliases for complex types
• Document unusual type choices
• Maintain consistency across codebase

7. Annotation Placement

class User
  # Class-level annotations at top
  # @rbs generic T

  # Instance variable annotations
  # @rbs @items: Array[T]

  # Method annotation immediately before method
  # @rbs (T item) -> void
  def add(item)
    @items << item
  end
end

Example

Original Ruby:

class Calculator
  def initialize
    @history = []
  end

  def add(a, b)
    result = a + b
    @history << result
    result
  end

  def history
    @history.dup
  end
end

Annotated Ruby:

class Calculator
  # @rbs @history: Array[Numeric]

  # @rbs () -> void
  def initialize
    @history = []
  end

  # @rbs (Numeric a, Numeric b) -> Numeric
  def add(a, b)
    result = a + b
    @history << result
    result
  end

  # @rbs () -> Array[Numeric]
  def history
    @history.dup
  end
end

8. Converting to Separate RBS

Inline annotations can be extracted to separate files:

rbs prototype rb --out-dir=sig lib/user.rb