YARD cheatsheet

yardoc_cheatsheet.md

YARD CHEATSHEET http://yardoc.org

cribbed from http://pastebin.com/xgzeAmBn

Templates to remind you of the options and formatting for the different types of objects you might want to document using YARD.

Modules

# Namespace for classes and modules that handle serving documentation over HTTP
#
# @abstract Subclass and override {#run} to implement
#   a custom Threadable class.
# @api description
#   Note: The special name @api private does display a notice in documentation if it is listed, 
#   letting users know that the method is not to be used by external components.
# @author Foo Bar <[email protected]>
# @private
# @since 0.6.0
# @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.
# @version 2.0

Classes

# Abstract base class for CLI utilities. Provides some helper methods for
# the option parser
# 
# @abstract Marks a class/module/method as abstract with optional implementor information.
# @api description
# @author Full Name
# @deprecated Describe the reason or provide alt. references here
# @example Optional title
     Code block
# @note Adds an emphasized note at the top of the docstring for the object
# @private
# @see http://ntp.org/documentation.html NTP Documentation
# @since 1.2.4
# @todo Add support for Jabberwocky service.
# @version 2.0

Methods

# An alias to {Parser::SourceParser}'s parsing method
# 
# @abstract Marks a class/module/method as abstract with optional implementor information.
# @author Donovan Bray
# @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.
# @example Reverse a string
#   "mystring.reverse" #=> "gnirtsym"
# @example Parse a glob of files
#   YARD.parse('lib/**/*.rb')
# @note Adds an emphasized note at the top of the docstring for the object
#
# @param [Hash] opts 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 
#
# @overload set(key, value)
#   Sets a value on key
#   @param key [Symbol] describe key param
#   @param value [Object] describe value param
# @overload set(value)
#   Sets a value on the default key +:foo+
#   @param value [Object] describe value param
#
# @param url [String] the URL of the page to download
# @param directory [String] the name of the directory to save to
#
# @private -> should not be used, because:
#    Declares that the logical visibility of an object is private.
#    In other words, it specifies that this method should be
#    marked private but cannot due to Ruby's visibility restrictions. 
#    This exists for classes, modules and constants
#    that do not obey Ruby's visibility rules.
#    For instance, an inner class might be considered “private”,
#    though Ruby would make no such distinction.
# @raise [ExceptionClass] description
# @raise [AccountBalanceError] if the account does not have
#   sufficient funds to perform the transaction
#
# @return [optional, types, ...] description
# @return [Fixnum] the size of the file
# @return [String] if a single object was returned
#   from the database.
# @return [Array<String>] if multiple objects were
#   returned.
# @return [String, #read] a string or object that responds to #read
# @return description here with no types
#
# @see http://ntp.org/documentation.html NTP Documentation
# @see NTPHelperMethods
# @since 1.2.4
# @todo Add support for Jabberwocky service.
#   There is an open source Jabberwocky library available
#   at http://jbrwcky.org that can be easily integrated.
# @version 2.0
# @yield [a, b, c] Gives 3 random numbers to the block
# @yieldparam [String] name the name that is yielded
# @yieldreturn [Fixnum] the number to add 5 to.

Blocks

# for block {|a, b, c| ... }
# @yield [a, b, c] Description of block
#
# @yieldparam [optional, types, ...] argname description
# @yieldreturn [optional, types, ...] description

Good stuff. How about the @!attribute and @!method directives?