cheatsheets/yard.md

title, category, intro

title	category	intro
YARD	Markup	Quick reference for YARD tags in Ruby documentation.

Method documentation

{: .-prime}

# 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.

Examples and links

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

{: .-one-column}

• https://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md
• https://www.rubydoc.info/gems/yard/file/docs/Tags.md
• https://yardoc.org/types.html {: .-also-see}