The gem is documented with a mix of rdoc and yard. We are migrating old rdocs to yard and writing new docs 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
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: 0.0.0.0:8808
When writing docs, it is usual to run:
# Reparses the library code on each request
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:
The following files have good examples of yard format:
keyboard_helpers.rb is a good example of comprehensive
documentation (it is in rdoc - pull requests welcome).
# method for interacting with instruments # # instruments #=> /Applications/Xcode.app/Contents/Developer/usr/bin/instruments # instruments(:version) #=> 5.1.1 # instruments(:sims) #=> < list of known simulators > # # @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
Indent code blocks 2 or more spaces.
# instruments #=> /Applications/Xcode.app/Contents/Developer/usr/bin/instruments # instruments(:version) #=> 5.1.1 # instruments(:sims) #=> < list of known simulators >
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)
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.
# 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
To mark an object as private, use the one of the following tags:
# @private # if +msg+ is a String, a new WaitError is returned. Otherwise +msg+ # ... def wait_error(msg) (msg.is_a?(String) ? WaitError.new(msg) : msg) end
# @!visibility private # raises an error by raising an error and conditionally takes a # screenshot based on the value of +screenshot_on_error+. # ... def handle_error_with_options(ex, timeout_message, screenshot_on_error)