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".
Full tag list here: https://rubydoc.info/gems/yard/file/docs/Tags.md#Tag_List
# 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
Indent on the next line to multi-line a tag.
# @tagname This is
# indented tag data
# but this is not
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 stringsArray<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}
- parametrized type form:
- 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.
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
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.
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.