Skip to content

Instantly share code, notes, and snippets.

@phansch
Forked from chetan/yardoc_cheatsheet.md
Last active June 10, 2024 16:08
Show Gist options
  • Save phansch/db18a595d2f5f1ef16646af72fe1fb0e to your computer and use it in GitHub Desktop.
Save phansch/db18a595d2f5f1ef16646af72fe1fb0e to your computer and use it in GitHub Desktop.
Improved YARD cheatsheet

NOTE: This is outdated. Check the comments below for more up-to-date forks of this gist.

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.

Linking Objects {...}

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}

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

Method parameters

# @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.
# @param [Hash<Symbol, String>] a hash with symbol keys and string values
#
# The options parsed out of the commandline.
# Default options are:
#   :format => :dot

Examples

# @example Reverse a string
#   "mystring".reverse #=> "gnirtsym"
#
# @example Parse a glob of files
#   YARD.parse('lib/**/*.rb')

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

Exceptions

# @raise [ExceptionClass] description

Return values

# @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
@phansch
Copy link
Author

phansch commented May 14, 2019

@chriscz thanks, updated!

@sleekweasel
Copy link

I'm curious:

# @return [String, nil] returns a nullable string

so how do I represent a hash of symbol to nullable string; like this?

# @param [Hash<Symbol, [String, nil]>] a hash with symbol keys and nullable string values

@DNA
Copy link

DNA commented Nov 11, 2019

@sleekweasel The type field can be quite free form, but you can check the current conventions on https://yardoc.org/types.

In your case, it would be

# @param [Hash{Symbol => String, nil}] a hash with symbol keys and nullable string values

@dmitchell
Copy link

dmitchell commented Apr 7, 2020

How to repr return multiple values?

# @return [Hash{Number => PartnerLocationIdMap}, Array(LocationMultiple)]

@chriscz
Copy link

chriscz commented Apr 9, 2020

@dmitchell That looks correct. When you say Array(LocationMultiple) then its a list with single element 1-tuple, i.e. return [LocationMultiple.new]
If you want multiple items in the array you have to use Array<LocationMultiple> which will work for return [LocationMultiple.new, LocationMultiple.new, ...]

@dolzenko
Copy link

Need this in PDF badly :)

@dolzenko
Copy link

Also doesn't document the fact that parameter name can precede the type

 # @param request [Request] the request object

from https://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md

@chriscz
Copy link

chriscz commented Sep 13, 2023

PRs welcome here: https://github.com/chriscz/cheatsheets (alsoe @dolzenko check the output folder for a PDF)

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