-
Notifications
You must be signed in to change notification settings - Fork 600
Documentation browsing
- View a method's documentation
- View basic method information
- Access ri documentation
- View documentation for Ruby Core (C code)
The ability to retrieve method documentation is very important when learning a new library or code base. And the ability to read documentation in a REPL environment, where you can interact with the methods on live code is particularly useful. Pry does this without relying on any external utilities, it simply extracts what it needs at run-time from the source file. This makes Pry's native documentation viewer potentially more useful than tools such as ri as Pry does not rely on docs being pre-generated when a gem is installed.
To retrieve a method's documentation use the show-doc command. show-doc accepts the same options as the show-method command and, like show-method extracts what it needs at run-time.
show-doc has a basic understanding of both the rdoc and YARD documentation formats and will attempt to render the documentation properly and with syntax highlighting.
Note that, as in the case of show-method, you can simply type show-doc (with no arguments) to operate on the 'current method' (when Pry is invoked inside a method using binding.pry at runtime).
Note: show-doc 'number of lines' shows the total lines of documentation.
Aliases: ?
Example: rdoc
pry(main)> show-doc Set#add
From: /Users/john/.rvm/rubies/ruby-1.9.2-p180/lib/ruby/1.9.1/set.rb @ line 228:
Number of lines: 2
signature: add(o)
Adds the given object to the set and returns self. Use merge to
add many elements at once.
pry(main)>
Example: YARD
pry(main)> show-doc Pry#r
From: /Users/john/ruby/projects/pry/lib/pry/pry_instance.rb @ line 249:
Number of lines: 10
signature: r(target=?, eval_string=?)
Perform a read.
If no parameter is given, default to top-level (main).
This is a multi-line read; so the read continues until a valid
Ruby expression is received.
Pry commands are also accepted here and operate on the target.
param [Object, Binding] target The receiver of the read.
param [String] eval_string Optionally Prime eval_string with a start value.
return [String] The Ruby expression.
example
Pry.new.r(Object.new)
pry(main)>
The stat command displays basic information about a method, including: its arity, its owner, its signature (if possible), and its type (i.e whether it's bound or unbound).
Example:
pry(main)> stat Pry#r
Method Information:
--
Name: Pry#r
Owner: Pry
Type: Unbound
Arity: -1
Method Signature: r(target=?, eval_string=?)
pry(main)>
The standard ri shell command can be accessed from within a Pry session using exactly the same syntax it has on the command line.
Example:
pry(main)> ri Fixnum#+
Fixnum#+
(from ruby site)
------------------------------------------------------------------------------
fix + numeric -> numeric_result
------------------------------------------------------------------------------
Performs addition: the class of the resulting object depends on the class of
numeric and on the magnitude of the result.
pry(main)>
When the pry-doc plugin is installed (gem install pry-doc) the C documentation for Ruby core methods (MRI) become available. As with pure Ruby methods, the show-doc command is used to display the documentation.
Example:
pry(main)> show-doc Object#extend
From: eval.c in Ruby Core (C Method):
Number of lines: 19
signature: extend(*)
Adds to _obj_ the instance methods from each module given as a
parameter.
module Mod
def hello
"Hello from Mod.\n"
end
end
class Klass
def hello
"Hello from Klass.\n"
end
end
k = Klass.new
k.hello #=> "Hello from Klass.\n"
k.extend(Mod) #=> #<Klass:0x401b3bc8>
k.hello #=> "Hello from Mod.\n"
pry(main)>