Quick reference for YARD tags in Ruby documentation.

Method documentation

# Downloads a page.
#
# @param url [String] the page URL
# @param directory [String] the output directory
# @return [String] the saved file path
# @raise [DownloadError] if the request fails
# @example Download into the default directory
#   download("https://example.com/")
def download(url, directory: "pages")
end

YARD tags begin with @ at the start of a comment line.

Parameters and return values

Parameters

# @param name [String] the user name
# @param count [Integer] the number of retries
# @param enabled [Boolean] whether retries are enabled

For keyword parameters, use @param.

Return values

# @return [String] the matching name
# @return [nil] if no match exists

Use multiple @return tags for distinct return cases.

Exceptions

# @raise [AccountBalanceError] if funds are insufficient

Options hash

# @param opts [Hash] message options
# @option opts [String] :subject the subject
# @option opts [String] :from ("nobody") the sender
# @option opts [String] :to the recipient
# @option opts [String] :body ("") the message body

Use @option for keys inside an options hash, not for keyword parameters.

Types

Common forms

Form Meaning
[String] One type
[String, nil] Alternative types
[Array<String>] Collection members
[Hash{Symbol => String}] Key and value types
[#read] Duck type
[Boolean] true or false
[void] Return value unused

YARD type declarations are conventions rather than Ruby runtime checks.

Reference tags

# @param user [String] the user name
# @param host [String] the host name
def clean(user, host)
end

# @param (see #clean)
def activate(user, host)
end

(see OBJECT) copies matching tag data from another documented object.

Example

# @example Reverse a string
#   "hello".reverse #=> "olleh"

The optional text after @example becomes the example title.

Object references

{User}
{User#name}
{User#name Display name}

Common tags

Tag Use
@api API audience
@author Author name
@deprecated Replacement guidance
@example Usage example
@note Important note
@option Options hash key
@param Method parameter
@private Private API
@raise Raised exception
@return Return value
@see Related object or URL
@since First release
@todo Pending work
@yieldparam Block parameter
@yieldreturn Block return value

Also see

0 Comments for this cheatsheet. Write yours!