1
0
Fork 0
mirror of https://github.com/pry/pry.git synced 2022-11-09 12:35:05 -05:00

Fix various mangled documentation

This commit is contained in:
Ryan Fitzgerald 2012-06-26 22:30:00 -07:00
parent 0af52b82ab
commit e14ee9a6f4
11 changed files with 108 additions and 117 deletions

View file

@ -33,9 +33,9 @@ class Pry
# Pry's line buffer.
#
# @param [String] fn The name of a file, or "(pry)".
# @param [Symbol] code_type (:ruby) The type of code the file contains.
# @param [Symbol] code_type The type of code the file contains.
# @return [Code]
def from_file(fn, code_type=nil)
def from_file(fn, code_type = nil)
if fn == Pry.eval_path
f = Pry.line_buffer.drop(1)
else
@ -56,8 +56,8 @@ class Pry
#
# @param [::Method, UnboundMethod, Proc, Pry::Method] meth The method
# object.
# @param [Fixnum, nil] The line number to start on, or nil to use the
# method's original line numbers.
# @param [Fixnum, nil] start_line The line number to start on, or nil to
# use the method's original line numbers.
# @return [Code]
def from_method(meth, start_line=nil)
meth = Pry::Method(meth)
@ -112,6 +112,7 @@ class Pry
end
end
# @return [Symbol] The type of code stored in this wrapper.
attr_accessor :code_type
# Instantiate a `Code` object containing code from the given `Array`,
@ -120,8 +121,8 @@ class Pry
# empty `Code` object and then use `#push` to insert the lines.
#
# @param [Array<String>, String, IO] lines
# @param [Fixnum?] (1) start_line
# @param [Symbol?] (:ruby) code_type
# @param [Fixnum?] start_line
# @param [Symbol?] code_type
def initialize(lines=[], start_line=1, code_type=:ruby)
if lines.is_a? String
lines = lines.lines
@ -210,7 +211,7 @@ class Pry
# Remove all lines except for the `lines` up to and excluding `line_num`.
#
# @param [Fixnum] line_num
# @param [Fixnum] (1) lines
# @param [Fixnum] lines
# @return [Code]
def before(line_num, lines=1)
return self unless line_num
@ -224,7 +225,7 @@ class Pry
# `line_num`.
#
# @param [Fixnum] line_num
# @param [Fixnum] (1) lines
# @param [Fixnum] lines
# @return [Code]
def around(line_num, lines=1)
return self unless line_num
@ -237,7 +238,7 @@ class Pry
# Remove all lines except for the `lines` after and excluding `line_num`.
#
# @param [Fixnum] line_num
# @param [Fixnum] (1) lines
# @param [Fixnum] lines
# @return [Code]
def after(line_num, lines=1)
return self unless line_num
@ -262,7 +263,7 @@ class Pry
# Format output with line numbers next to it, unless `y_n` is falsy.
#
# @param [Boolean?] (true) y_n
# @param [Boolean?] y_n
# @return [Code]
def with_line_numbers(y_n=true)
alter do
@ -273,7 +274,7 @@ class Pry
# Format output with a marker next to the given `line_num`, unless `line_num`
# is falsy.
#
# @param [Fixnum?] (1) line_num
# @param [Fixnum?] line_num
# @return [Code]
def with_marker(line_num=1)
alter do
@ -285,7 +286,7 @@ class Pry
# Format output with the specified number of spaces in front of every line,
# unless `spaces` is falsy.
#
# @param [Fixnum?] (0) spaces
# @param [Fixnum?] spaces
# @return [Code]
def with_indentation(spaces=0)
alter do

View file

@ -68,15 +68,12 @@ class Pry
end
# Create a new command with the given properties.
#
# @param String/Regex match the thing that triggers this command
# @param String description the description to appear in {help}
# @param Hash options behavioural options (@see {Pry::CommandSet#command})
# @param Module helpers a module of helper functions to be included.
# @param Proc &block (optional, a block, used for BlockCommands)
#
# @return Class (a subclass of Pry::Command)
#
# @param [String, Regex] match The thing that triggers this command
# @param [String] description The description to appear in `help`
# @param [Hash] options Behavioral options (see {Pry::CommandSet#command})
# @param [Module] helpers A module of helper functions to be included.
# @yield optional, used for BlockCommands
# @return [Class] (a subclass of {Pry::Command})
def subclass(match, description, options, helpers, &block)
klass = Class.new(self)
klass.send(:include, helpers)
@ -88,9 +85,8 @@ class Pry
end
# Should this command be called for the given line?
#
# @param String a line input at the REPL
# @return Boolean
# @param [String] val A line input at the REPL
# @return [Boolean]
def matches?(val)
command_regex =~ val
end
@ -109,8 +105,8 @@ class Pry
# /\.*(.*)/.match_score("...foo") #=> 3
# 'hi'.match_score("hi there") #=> 2
#
# @param String a line input at the REPL
# @return Fixnum
# @param [String] val A line input at the REPL
# @return [Fixnum]
def match_score(val)
if command_regex =~ val
Regexp.last_match.size > 1 ? Regexp.last_match.begin(1) : Regexp.last_match.end(0)
@ -165,7 +161,7 @@ class Pry
end
# Properties of one execution of a command (passed by {Pry#run_command} as a hash of
# context and expanded in {#initialize}
# context and expanded in `#initialize`
attr_accessor :output
attr_accessor :target
attr_accessor :captures
@ -214,8 +210,7 @@ class Pry
# Instantiate a command, in preparation for calling it.
#
# @param Hash context The runtime context to use with this command.
# @param [Hash] context The runtime context to use with this command.
def initialize(context={})
self.context = context
self.target = context[:target]
@ -255,8 +250,6 @@ class Pry
# Display a warning if a command collides with a local/method in
# the current scope.
# @param [String] command_name_match The name of the colliding command.
# @param [Binding] target The current binding context.
def check_for_command_collision(command_match, arg_string)
collision_type = target.eval("defined?(#{command_match})")
collision_type ||= 'local-variable' if arg_string.match(%r{\A\s*[-+*/%&|^]*=})
@ -268,15 +261,20 @@ class Pry
rescue Pry::RescuableException
end
# Extract necessary information from a line that Command.matches? this command.
# Extract necessary information from a line that Command.matches? this
# command.
#
# @param String the line of input
# @return [
# String the portion of the line that matched with the Command match
# String a string of all the arguments (i.e. everything but the match)
# Array the captures caught by the command_regex
# Array args the arguments got by splitting the arg_string
# ]
# Returns an array of four elements:
#
# ```
# [String] the portion of the line that matched with the Command match
# [String] a string of all the arguments (i.e. everything but the match)
# [Array] the captures caught by the command_regex
# [Array] the arguments obtained by splitting the arg_string
# ```
#
# @param [String] val The line of input
# @return [Array]
def tokenize(val)
val.replace(interpolate_string(val)) if command_options[:interpolate]
@ -305,9 +303,8 @@ class Pry
end
# Process a line that Command.matches? this command.
#
# @param String the line to process
# @return Object or Command::VOID_VALUE
# @param [String] line The line to process
# @return [Object, Command::VOID_VALUE]
def process_line(line)
command_match, arg_string, captures, args = tokenize(line)
@ -349,12 +346,14 @@ class Pry
private :pass_block
# Run the command with the given {args}.
# Run the command with the given `args`.
#
# This is a public wrapper around {#call} which ensures all preconditions are met.
# This is a public wrapper around `#call` which ensures all preconditions
# are met.
#
# @param *[String] the arguments to pass to this command.
# @return Object the return value of the {#call} method, or Command::VOID_VALUE
# @param [Array<String>] args The arguments to pass to this command.
# @return [Object] The return value of the `#call` method, or
# {Command::VOID_VALUE}.
def call_safely(*args)
unless dependencies_met?
gems_needed = Array(command_options[:requires_gem])
@ -382,10 +381,9 @@ class Pry
private
# Run the {#call} method and all the registered hooks.
#
# @param *String the arguments to #{call}
# @return Object the return value from #{call}
# Run the `#call` method and all the registered hooks.
# @param [Array<String>] args The arguments to `#call`
# @return [Object] The return value from `#call`
def call_with_hooks(*args)
self.class.hooks[:before].each do |block|
instance_exec(*args, &block)
@ -401,10 +399,9 @@ class Pry
end
# Fix the number of arguments we pass to a block to avoid arity warnings.
#
# @param Number the arity of the block
# @param Array the arguments to pass
# @return Array a (possibly shorter) array of the arguments to pass
# @param [Fixnum] arity The arity of the block
# @param [Array] args The arguments to pass
# @return [Array] A (possibly shorter) array of the arguments to pass
def correct_arg_arity(arity, args)
case
when arity < 0
@ -428,9 +425,8 @@ class Pry
alias_method :opts, :context
# Call the block that was registered with this command.
#
# @param *String the arguments passed
# @return Object the return value of the block
# @param [Array<String>] args The arguments passed
# @return [Object] The return value of the block
def call(*args)
instance_exec(*correct_arg_arity(block.arity, args), &block)
end
@ -442,24 +438,26 @@ class Pry
# A super-class ofr Commands with structure.
#
# This class implements the bare-minimum functionality that a command should have,
# namely a --help switch, and then delegates actual processing to its subclasses.
# This class implements the bare-minimum functionality that a command should
# have, namely a --help switch, and then delegates actual processing to its
# subclasses.
#
# Create subclasses using {Pry::CommandSet#create_command}, and override the {options(opt)} method
# to set up an instance of Slop, and the {process} method to actually run the command. If
# necessary, you can also override {setup} which will be called before {options}, for example to
# require any gems your command needs to run, or to set up state.
# Create subclasses using {Pry::CommandSet#create_command}, and override the
# `options(opt)` method to set up an instance of Slop, and the `process`
# method to actually run the command. If necessary, you can also override
# `setup` which will be called before `options`, for example to require any
# gems your command needs to run, or to set up state.
class ClassCommand < Command
attr_accessor :opts
attr_accessor :args
# Set up {opts} and {args}, and then call {process}
# Set up `opts` and `args`, and then call `process`.
#
# This function will display help if necessary.
#
# @param *String the arguments passed
# @return Object the return value of {process} or VOID_VALUE
# @param [Array<String>] args The arguments passed
# @return [Object] The return value of `process` or VOID_VALUE
def call(*args)
setup
@ -488,7 +486,7 @@ class Pry
end
end
# A function called just before {options(opt)} as part of {call}.
# A function called just before `options(opt)` as part of `call`.
#
# This function can be used to set up any context your command needs to run, for example
# requiring gems, or setting default values for options.
@ -504,7 +502,7 @@ class Pry
#
# NOTE: please don't do anything side-effecty in the main part of this method,
# as it may be called by Pry at any time for introspection reasons. If you need
# to set up default values, use {setup} instead.
# to set up default values, use `setup` instead.
#
# @example
# def options(opt)
@ -517,11 +515,12 @@ class Pry
# The actual body of your command should go here.
#
# The {opts} mehod can be called to get the options that Slop has passed,
# and {args} gives the remaining, unparsed arguments.
# The `opts` mehod can be called to get the options that Slop has passed,
# and `args` gives the remaining, unparsed arguments.
#
# The return value of this method is discarded unless the command was created
# with :keep_retval => true, in which case it is returned to the repl.
# The return value of this method is discarded unless the command was
# created with `:keep_retval => true`, in which case it is returned to the
# repl.
#
# @example
# def process

View file

@ -92,7 +92,7 @@ class Pry
# @param [String, Regexp] match The start of invocations of this command.
# @param [String] description A description of the command.
# @param [Hash] options The optional configuration parameters, see {#command}
# @param &Block The class body's definition.
# @yield The class body's definition.
#
# @example
# Pry::Commands.create_command "echo", "echo's the input", :shellwords => false do
@ -153,7 +153,7 @@ class Pry
end
# Add a given command object to this set.
# @param Command the subclass of Pry::Command you wish to add.
# @param [Command] command The subclass of Pry::Command you wish to add.
def add_command(command)
commands[command.match] = command
end
@ -240,7 +240,7 @@ class Pry
# Rename a command. Accepts either match or listing for the search.
#
# @param [String, Regexp] new_name The new match for the command.
# @param [String, Regexp] new_match The new match for the command.
# @param [String, Regexp] search The command's current match or listing.
# @param [Hash] options The optional configuration parameters,
# accepts the same as the `command` method, but also allows the
@ -265,8 +265,8 @@ class Pry
# Sets or gets the description for a command (replacing the old
# description). Returns current description if no description
# parameter provided.
# @param [String, Regexp] match The command match.
# @param [String] description The command description.
# @param [String, Regexp] search The command match.
# @param [String?] description (nil) The command description.
# @example Setting
# MyCommands = Pry::CommandSet.new do
# desc "help", "help description"
@ -303,8 +303,7 @@ class Pry
end
# Find a command that matches the given line
#
# @param [String] the line that may be a command invocation
# @param [String] val The line that might be a command invocation
# @return [Pry::Command, nil]
def find_command(val)
commands.values.select{ |c| c.matches?(val) }.sort_by{ |c| c.match_score(val) }.last
@ -312,9 +311,8 @@ class Pry
alias_method :[], :find_command
# Find the command that the user might be trying to refer to.
#
# @param [String] the user's search.
# @return [Pry::Command, nil]
# @param [String] search The user's search.
# @return [Pry::Command?]
def find_command_for_help(search)
find_command(search) || (begin
find_command_by_match_or_listing(search)
@ -324,19 +322,16 @@ class Pry
end
# Is the given line a command invocation?
#
# @param [String]
# @param [String] val
# @return [Boolean]
def valid_command?(val)
!!find_command(val)
end
# Process the given line to see whether it needs executing as a command.
#
# @param String the line to execute
# @param Hash the context to execute the commands with
# @return CommandSet::Result
#
# @param [String] val The line to execute
# @param [Hash] context The context to execute the commands with
# @return [CommandSet::Result]
def process_line(val, context={})
if command = find_command(val)
context = context.merge(:command_set => self)
@ -347,7 +342,7 @@ class Pry
end
end
# @nodoc used for testing
# @private (used for testing)
def run_command(context, match, *args)
command = commands[match] or raise NoCommandError.new(match, self)
command.new(context).call_safely(*args)

View file

@ -8,7 +8,7 @@ class Pry
module InputCompleter
if Readline.respond_to?("basic_word_break_characters=")
Readline.basic_word_break_characters= " \t\n\"\\'`><=;|&{("
Readline.basic_word_break_characters = " \t\n\"\\'`><=;|&{("
end
Readline.completion_append_character = nil

View file

@ -175,10 +175,7 @@ class Pry
# "Ut enim ad minim veniam."
# USAGE
#
# @param [String] The text from which to remove indentation
# @return [String], The text with indentation stripped.
#
# @copyright Heavily based on textwrap.dedent from Python, which is:
# Heavily based on textwrap.dedent from Python, which is:
# Copyright (C) 1999-2001 Gregory P. Ward.
# Copyright (C) 2002, 2003 Python Software Foundation.
# Written by Greg Ward <gward@python.net>
@ -186,6 +183,8 @@ class Pry
# Licensed under <http://docs.python.org/license.html>
# From <http://hg.python.org/cpython/file/6b9f0a6efaeb/Lib/textwrap.py>
#
# @param [String] text The text from which to remove indentation
# @return [String] The text with indentation stripped.
def unindent(text)
# Empty blank lines
text = text.sub(/^[ \t]+$/, '')

View file

@ -46,19 +46,18 @@ class Pry
Pry.color ? "\e[1m#{text}\e[0m" : text.to_s
end
# Returns _text_ in the default foreground colour.
# Returns `text` in the default foreground colour.
# Use this instead of "black" or "white" when you mean absence of colour.
#
# @param [String, #to_s]
# @return [String] _text_
# @param [String, #to_s] text
# @return [String]
def default(text)
text.to_s
end
alias_method :bright_default, :bold
# Executes _block_ with _Pry.color_ set to false.
#
# @param [Proc]
# Executes the block with `Pry.color` set to false.
# @yield
# @return [void]
def no_color &block
boolean = Pry.config.color
@ -68,9 +67,8 @@ class Pry
Pry.config.color = boolean
end
# Executes _block_ with _Pry.config.pager_ set to false.
#
# @param [Proc]
# Executes the block with `Pry.config.pager` set to false.
# @yield
# @return [void]
def no_pager &block
boolean = Pry.config.pager

View file

@ -173,7 +173,7 @@ class Pry
# Return a specific hook for a given event.
# @param [Symbol] event_name The name of the event.
# @param [Symbol[ hook_name The name of the hook
# @param [Symbol] hook_name The name of the hook
# @return [#call] The requested hook.
# @example
# my_hooks = Pry::Hooks.new.add_hook(:before_session, :say_hi) { puts "hi!" }

View file

@ -233,8 +233,8 @@ class Pry
# Given a string of Ruby code, use CodeRay to export the tokens.
#
# @param String The Ruby to lex.
# @return [Array] An Array of pairs of [token_value, token_type]
# @param [String] string The Ruby to lex
# @return [Array] An Array of pairs of [token_value, token_type]
def tokenize(string)
tokens = CodeRay.scan(string, :ruby)
tokens = tokens.tokens.each_slice(2) if tokens.respond_to?(:tokens) # Coderay 1.0.0
@ -247,7 +247,7 @@ class Pry
# normal strings (which can't be nested) we assume that CodeRay correctly pairs
# open-and-close delimiters so we don't bother checking what they are.
#
# @param String The token (of type :delimiter)
# @param [String] token The token (of type :delimiter)
def track_delimiter(token)
case token
when /^<<-(["'`]?)(.*)\\1/

View file

@ -210,7 +210,7 @@ class Pry
# A new instance of `Pry::Method` wrapping the given `::Method`, `UnboundMethod`, or `Proc`.
#
# @param [::Method, UnboundMethod, Proc] method
# @param [Hash] known_info, can be used to pre-cache expensive to compute stuff.
# @param [Hash] known_info Can be used to pre-cache expensive to compute stuff.
# @return [Pry::Method]
def initialize(method, known_info={})
@method = method
@ -464,8 +464,8 @@ class Pry
buffer
end
# @param [Class,Module] the ancestors to investigate
# @return [Method] the unwrapped super-method
# @param [Class, Module] ancestors The ancestors to investigate
# @return [Method] The unwrapped super-method
def super_using_ancestors(ancestors, times=1)
next_owner = self.owner
times.times do
@ -514,8 +514,8 @@ class Pry
#
# @param [Object] receiver
# @param [String] method_name
def initialize(*args)
@receiver, @name = *args
def initialize(receiver, method_name)
@receiver, @name = receiver, method_name
end
# Is the method undefined? (aka `Disowned`)

View file

@ -191,7 +191,7 @@ class Pry
# Run a Pry command from outside a session. The commands available are
# those referenced by `Pry.commands` (the default command set).
# @param [String] arg_string The Pry command (including arguments,
# @param [String] command_string The Pry command (including arguments,
# if any).
# @param [Hash] options Optional named parameters.
# @return [Object] The return value of the Pry command.

View file

@ -38,9 +38,8 @@ class Pry
nil
end
# Create a new WrappedModule
# @raise ArgumentError, if the argument is not a Module
# @param [Module]
# @raise [ArgumentError] if the argument is not a `Module`
# @param [Module] mod
def initialize(mod)
raise ArgumentError, "Tried to initialize a WrappedModule with a non-module #{mod.inspect}" unless ::Module === mod
@wrapped = mod