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.
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 |
0 Comments for this cheatsheet. Write yours!