YARD Doc Cheatsheet

YARD Doc Cheatsheet.md

Documenting With YARD

This document is a condensed version of this page: https://rubydoc.info/gems/yard/file/docs/Tags.md

YARD is compatible with all RDoc sytax. YARD's power comes from its meta-data syntax, "tags".

Tags

Full tag list here: https://rubydoc.info/gems/yard/file/docs/Tags.md#Tag_List

Common Example

# Converts the object into textual markup given a specific format.
#
# @param format [Symbol] the format type, `:text` or `:html`
# @return [String] the object converted into the expected format.
def to_format(format = :html)
  # format the object
end

Multi-Line

Indent on the next line to multi-line a tag.

# @tagname This is
#   indented tag data
# but this is not

Types Specifier List

A types specifier list is a comma separated list of types, most often classes or modules, but occasionally literals. For example, the following @return tag lists a set of types returned by a method:

# Finds an object or list of objects in the db using a query
# @return [String, Array<String>, nil] the object or objects to
#   find in the database. Can be nil.
def find(query) finder_code_here end

The types list can contain any of these:

• Class or Module Types (including the Ruby-non-existant Boolean)
• Parametrized Types Type<SubType, OtherSubType, ...>
  • Array<String> is an array of strings
  • Array<String, Fixnum> can contain any amount of Strings or Fixnums, in any order.
• Duck Types
  • are identified by method names beginning with the "#" prefix
  • # @param io [#read] the input object to read from
• Hashes
  • parametrized type form: Hash<KeyType, ValueType>
  • hash specific syntax: Hash{KeyTypes=>ValueTypes}
• Order-Dependent Lists
  • a set of types surrounded by "()" and separated by commas
  • must contain exactly those types in exactly the order specified
  • Array<(String, Fixnum, Hash)> would be an array with three elements: string, fixnum, and hash, in exactly that order
• Literals
  • true, false, nil — used when a method returns these explicit literal values. Note that if your method returns both true or false, you should use the Boolean conventional type instead.
  • self — has the same meaning as Ruby's "self" keyword in the context of parameters or return types. Recommended mostly for @return tags that are chainable.
  • void — indicates that the type for this tag is explicitly undefined. Mostly used to specify @return tags that do not care about their return value.

Reference Tags

If a tag's data begins with (see OBJECT) it is considered a "reference tag". A reference tag literally copies the tag data by the given tag name from the specified OBJECT. For instance, a method may copy all @param tags from a given object using the reference tag syntax:

# @param user [String] the username for the operation
# @param host [String] the host that this user is associated with
# @param time [Time] the time that this operation took place
def clean(user, host, time = Time.now) end

# @param (see #clean)
def activate(user, host, time = Time.now) end

Running YARD

yard server Documentation Server

The yard server command serves documentation for a local project or all installed RubyGems. To serve documentation for a project you are working on, simply run:

yard server --reload

And the project inside the current directory will be parsed (if the source has not yet been scanned by YARD) and served at http://localhost:8808.

The --reload flag allows the serving of documentation on a project while you document it so that you can preview the results by refreshing the page in your browser.

yard doc

Aliased as yardoc, generates the docs. There are a lot of options for including / excluding files, cache control, etc. use --help to see all options.