Improved YARD CHEATSHEET http://yardoc.org
forked from https://gist.github.com/chetan/1827484 which is from early 2012 and contains outdated information.
Templates to remind you of the options and formatting for the different types of objects you might want to document using YARD.
To link another "object" (class, method, module, etc.), use the format:
{ObjectName#method OPTIONAL_TITLE}
{Class::CONSTANT My constant's title}
{#method_inside_current_namespace}
# An alias to {Parser::SourceParser}'s parsing method
#
# @author Donovan Bray
#
# @see http://example.com Description of URL
# @see SomeOtherClass#method
#
# @deprecated Use {#my_new_method} instead of this method because
# it uses a library that is no longer supported in Ruby 1.9.
# The new method accepts the same parameters.
#
# @abstract
# @private
# @param opts [Hash] the options to create a message with.
# @option opts [String] :subject The subject
# @option opts [String] :from ('nobody') From address
# @option opts [String] :to Recipient email
# @option opts [String] :body ('') The email's body
def send_email(opts = {}) end
# @param (see User#initialize)
# @param opts [OptionParser] the option parser object
# @param args [Array<String>] the arguments passed from input. This
# array will be modified.
# @param list [Array<String, Symbol>] the list of strings and symbols.
# @param hash [Hash<Symbol, String>] a hash with symbol keys and string values
#
# The options parsed out of the commandline.
# Default options are:
# :format => :dot
# @example Reverse a string
# "mystring".reverse #=> "gnirtsym"
#
# @example Parse a glob of files
# YARD.parse('lib/**/*.rb')
# Namespace for classes and modules that handle serving documentation over HTTP
# @since 0.6.0
# Abstract base class for CLI utilities. Provides some helper methods for
# the option parser
#
# @author Full Name
# @abstract
# @since 0.6.0
# @deprecated Describe the reason or provide alt. references here
#
# # Attributes can be documented directly like this
# attr_reader :hello
#
# If you generate attributes via meta programming, use
# @!attribute [r | w | rw] attribute_name
See https://www.rubydoc.info/gems/yard/file/docs/Tags.md#attribute for more information on documenting attributes.
# @raise [ExceptionClass] description
# @return [optional, types, ...] description
# @return [true] always returns true
# @return [void]
# @return [String, nil] the contents of our object or nil
# if the object has not been filled with data.
#
# We don't care about the "type" here:
# @return the object
#
# @return [String, #read] a string or object that responds to #read
# @return description here with no types
# @todo Add support for Jabberwocky service
# There is an open source Jabberwocky library available
# at http://somesite.com that can be integrated easily
# into the project.
# for block {|a, b, c| ... }
# @yield [a, b, c] Description of block
#
# @yieldparam [optional, types, ...] argname description
# @yieldreturn [optional, types, ...] description
@phansch, would you consider updating
@param
to match to the documentation indicated by yardoc.org?I see https://yardoc.org/guides/ links "Getting Started" to https://rubydoc.info/gems/yard/file/docs/GettingStarted.md, and that page gives the following, with the name of the param (
format
) coming before the type of the param ([Symbol]
):The present version of this gist has the type of the param (
[Hash]
) coming after the name of the param (opts
) :