Yard Docs

This gem is documented with yard.

Build the Docs Locally

$ be rake yard
Files:          38
Modules:        26 (   13 undocumented)
Classes:        14 (   11 undocumented)
Constants:      31 (   21 undocumented)
Methods:       466 (  242 undocumented)
 46.55% documented

Docs are generated in the docs directory.

See What is Undocumented

$ be yard stats --list-undoc

Start a Local Server

$ be yard server
> YARD 0.8.7.3 documentation server at http://0.0.0.0:8808
[2014-02-25 13:17:46] INFO  WEBrick 1.3.1
[2014-02-25 13:17:46] INFO  ruby 2.0.0 (2013-11-22) [x86_64-darwin13.0.0]
[2014-02-25 13:17:46] INFO  WEBrick::HTTPServer#start: pid=54296 port=8808

View docs here: http://0.0.0.0:8808

When writing docs, it is usual to run:

# Reparses the library code on each request
$ be yard server --reload

Documenting with Yard

The Yard syntax should be familiar to anyone who has used javadocs or doyxgen.

This page has details about the Yard markup tags and is extremely useful:

Examples

# method for interacting with instruments
#
# @example Find the instruments version
#   instruments(:version)
#
# @example A list of known simulators
#   instruments(:sims)
#
# @param [String] cmd controls the return value.  currently accepts nil,
#   :sims, and :version as valid parameters
# @return [String] based on the value of `cmd` version, a list known
#   simulators, or the path to the instruments binary
# @raise [ArgumentError] if invalid `cmd` is passed

code blocks

# ```
#  def example_code
#
#  end
# ```

tags that span multiple lines

Indent subsequent lines by 2 or more spaces (prefer 2 spaces).

# @param [String] cmd controls the return value.  currently accepts nil,
#   :sims, and :version as valid parameters

default argument values are auto-generated

A method like this:

# @param [String] cmd controls the return value.  currently accepts nil,
#   :sims, and :version as valid parameters
def instruments(cmd=nil)

will generate:

cmd (String) (defaults to: nil) — controls the return value. currently accepts nil, :sims, and :version as valid parameters

documenting option hashes

Default values can be specified by including them after the option key in ().

# @param [Hash] opts controls the content of the query string
# @option opts [Integer,nil] :with_tag (true) if non-nil the query string includes tag filter
# @option opts [Integer,nil] :with_clips_to_bounds (false) if non-nil the query string includes clipsToBounds filter

multiple return values

You can list multiple return tags for a method in the case where a method has distinct return cases. Each case should begin with “if …”

# @return [nil] if `key` does not exist
# @return [String] if the `key` exists then the value of +key+ (error)

You can also chain return values, but this freaks out RubyMine. :(

# 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

generics are allowed

# @param [Array<String, Integer, Float>] list a list of strings integers and floats

ignoring private APIs

The .yardopts file includes the --no-private option.

To mark an object as private, use this tag.

  • # @!visibility private

Objects that are within the (Ruby) scope of private will be recognized automatically by yard as private.

# @!visibility private
# Raises an error by raising a exception and conditionally takes a
# screenshot based on the value of `screenshot_on_error`.
# ...
def handle_error_with_options(ex, timeout_message, screenshot_on_error)