A Ruby Language Server

Solargraph and YARD

Solargraph uses YARD documentation to gather information about your project and its gem dependencies.

Documenting Your Gems

Run yard gems to generate documentation for your installed gems.

Run yard config --gem-install-yri to generate YARD documentation automatically when you install new gems.

Supported Tags and Directives

This section explains how Solargraph uses YARD for code intelligence and type checking. See the YARD Tags Overview for a list of all tags with example usage.


A method’s return type.

class Example
  # @return [String]
  def stringify
end # <= Recognized as a String

You can also use @return for attribute types.

class Example
  # @return [Integer]
  attr_reader :number


A method’s param type.

class Example
  # @param int [Integer]
  def take_a_number(int)
    int # <= Recognized as an Integer
end # Passes strict type checks'A') # Fails strict type checks


Use @yieldparam to specify the types of parameters accepted in a method’s yielded block.

class Example
  # @yieldparam [String]
  def change
    yield 'example'
end do |str|
  str # <= Recognized as a String


Use @overload to specify variations in the parameters a method can accept and the return type of each variation. Solargraph will use overloads to infer types from method calls.

class Example
  # Return one object according to its name or an array of objects from an
  # array of names.
  # @overload find(name)
  #   @param name [String]
  #   @return [Object]
  # @overload find(list)
  #   @param list [Array<String>]
  #   @return [Array<Object>]
  def find(*args); end

example =
example.find('Bob')           # => Object
example.find(['Bob', 'Jane']) # => Array<Object>


Solargraph will process @!attribute directives and add them to maps the same as if they were defined in runtime code.

class Example
  # @return [String]
  attr_accessor :foo

# @!attribute [rw] bar
  #   @return [String]
end # `foo` and `bar` are recognized as available attributes


Solargraph will process @!method directives and add the to maps the same as if they were defined in runtime code.

class Example
  # @return [String]
  def foo; end

  # @!method bar()
  #   @return [String]
end # `foo` and `bar` are recognized as available methods


Solargraph will parse and map any code in a @!parse directive the same as runtime code.

module ClassMethods
  def other_method; end

class Example
  # @!parse
  #   extend ClassMethods

Example. # `other_method` is recognized as an available method

Custom Tags and Directives

Solargraph extends YARD with several custom tags to help developers improve type inference.


Specify the type of a variable.

# @type [String]
str = method_returning_string
str # => String


Use @yieldself to indicate that a method’s yielded block will be bound to a different type.

module Example
  # @yieldself [String]
  def self.inside_string; end

Example.inside_string do
  # Solargraph knows that this block's `self` is a String, so String instance
  # methods like `upcase` are available here.


Sometimes developers want to add documentation for methods that are defined in external libraries, like gem dependencies. The @!override tag allows them to add or overwrite tags in an existing method.

# Specify the return type of the Ruby stdlib's Benchmark.measure method
# @!override Benchmark.measure
#   @return [Benchmark::Tms]

result = Benchmark.measure { puts 'test' }
result # => Benchmark::Tms