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.

@return

A method’s return type.

class Example
  # @return [String]
  def stringify
    'example'
  end
end

Example.new.stringify # <= Recognized as a String

You can also use @return for attribute types.

class Example
  # @return [Integer]
  attr_reader :number
end

@param

A method’s param type.

class Example
  # @param int [Integer]
  def take_a_number(int)
    int # <= Recognized as an Integer
  end
end

Example.new.take_a_number(100) # Passes strict type checks

Example.new.take_a_number('A') # Fails strict type checks

@yieldparam

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

class Example
  # @yieldparam [String]
  def change
    yield 'example'
  end
end

Example.new.change do |str|
  str # <= Recognized as a String
end

@overload

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
end

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

@!attribute

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

Example.new. # `foo` and `bar` are recognized as available attributes

@!method

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

Example.new. # `foo` and `bar` are recognized as available methods

@!parse

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

module ClassMethods
  def other_method; end
end

class Example
  # @!parse
  #   extend ClassMethods
end

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.

@type

Specify the type of a variable.

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

@yieldself

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
end

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

@!override

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