Create a gist now

Instantly share code, notes, and snippets.

Embed
What would you like to do?
YARD cheatsheet

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
# @since 0.6.0

Classes

# Abstract base class for CLI utilities. Provides some helper methods for
# the option parser
# 
# @author Full Name
# @abstract
# @since 0.6.0
# @attr [Types] attribute_name a full description of the attribute
# @attr_reader [Types] name description of a readonly attribute
# @attr_writer [Types] name description of writeonly attribute
# @deprecated Describe the reason or provide alt. references here

Methods

# 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 [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 
#
# @param (see User#initialize)
# @param [OptionParser] opts the option parser object
# @param [Array<String>] args the arguments passed from input. This
#   array will be modified.
# @param [Array<String, Symbol>] list the list of strings and symbols.
#
# 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')
#  
# @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

Anywhere

# @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.

Blocks

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

This comment has been minimized.

Show comment
Hide comment
@nixpulvis

nixpulvis Mar 22, 2013

This is a great reference, thank you.

Do you know what the best way to handle the remove and remove! situation, where you have 2 methods that do the same basic thing, I want to reference the documentation of the remove method and @see seems a bit to subtle.

nixpulvis commented Mar 22, 2013

This is a great reference, thank you.

Do you know what the best way to handle the remove and remove! situation, where you have 2 methods that do the same basic thing, I want to reference the documentation of the remove method and @see seems a bit to subtle.

@VirtuosoJoel

This comment has been minimized.

Show comment
Hide comment
@VirtuosoJoel

VirtuosoJoel Apr 30, 2013

I've started to use this kind of notation between closely related methods:

{MyClass#uniq!}

def uniq ...

VirtuosoJoel commented Apr 30, 2013

I've started to use this kind of notation between closely related methods:

{MyClass#uniq!}

def uniq ...

@axsuul

This comment has been minimized.

Show comment
Hide comment
@axsuul

axsuul Jan 11, 2018

Note that this reference sheet is outdated as of 2018

axsuul commented Jan 11, 2018

Note that this reference sheet is outdated as of 2018

@nimylian

This comment has been minimized.

Show comment
Hide comment
@nimylian

nimylian Jan 29, 2018

@axsuul can you provide some reference for that assertion?

nimylian commented Jan 29, 2018

@axsuul can you provide some reference for that assertion?

@ForeverZer0

This comment has been minimized.

Show comment
Hide comment
@ForeverZer0

ForeverZer0 Jun 22, 2018

@nimylian To answer your question, I assume what @axsuul was referring to was primarily the "Class" section above, while not technically "incorrect", is outdated and deprecated.

It clearly states that the @attr, @attr_reader, and @attr_writer tags are deprecated in favor of @!attribute [r|w] tag.
The former tags still work perfectly well, and do not issue any errors or warnings, but are technically deprecated. Those new to YARD and learning its syntax using a cheat-sheet would be better served to learn the the "modern" tags, not deprecated tags that may or may not exist in future releases.

Reference for Assertion

ForeverZer0 commented Jun 22, 2018

@nimylian To answer your question, I assume what @axsuul was referring to was primarily the "Class" section above, while not technically "incorrect", is outdated and deprecated.

It clearly states that the @attr, @attr_reader, and @attr_writer tags are deprecated in favor of @!attribute [r|w] tag.
The former tags still work perfectly well, and do not issue any errors or warnings, but are technically deprecated. Those new to YARD and learning its syntax using a cheat-sheet would be better served to learn the the "modern" tags, not deprecated tags that may or may not exist in future releases.

Reference for Assertion

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment