From e14ee9a6f41ddae5bd888f39296f0c2c88d80d6f Mon Sep 17 00:00:00 2001 From: Ryan Fitzgerald Date: Tue, 26 Jun 2012 22:30:00 -0700 Subject: [PATCH] Fix various mangled documentation --- lib/pry/code.rb | 25 +++--- lib/pry/command.rb | 119 ++++++++++++++--------------- lib/pry/command_set.rb | 31 ++++---- lib/pry/completion.rb | 2 +- lib/pry/helpers/command_helpers.rb | 7 +- lib/pry/helpers/text.rb | 16 ++-- lib/pry/hooks.rb | 2 +- lib/pry/indent.rb | 6 +- lib/pry/method.rb | 10 +-- lib/pry/pry_class.rb | 2 +- lib/pry/wrapped_module.rb | 5 +- 11 files changed, 108 insertions(+), 117 deletions(-) diff --git a/lib/pry/code.rb b/lib/pry/code.rb index 6cb66381..ad50465a 100644 --- a/lib/pry/code.rb +++ b/lib/pry/code.rb @@ -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, 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 diff --git a/lib/pry/command.rb b/lib/pry/command.rb index 9d9b0b67..8ab1f138 100644 --- a/lib/pry/command.rb +++ b/lib/pry/command.rb @@ -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] 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] 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] 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] 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 diff --git a/lib/pry/command_set.rb b/lib/pry/command_set.rb index 77a2e5a8..a38f36d5 100644 --- a/lib/pry/command_set.rb +++ b/lib/pry/command_set.rb @@ -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) diff --git a/lib/pry/completion.rb b/lib/pry/completion.rb index a1b1cbfb..c7fc1e0b 100644 --- a/lib/pry/completion.rb +++ b/lib/pry/completion.rb @@ -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 diff --git a/lib/pry/helpers/command_helpers.rb b/lib/pry/helpers/command_helpers.rb index 1f900a66..0f5582bf 100644 --- a/lib/pry/helpers/command_helpers.rb +++ b/lib/pry/helpers/command_helpers.rb @@ -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 @@ -186,6 +183,8 @@ class Pry # Licensed under # From # + # @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]+$/, '') diff --git a/lib/pry/helpers/text.rb b/lib/pry/helpers/text.rb index 502a5fc0..57a726a0 100644 --- a/lib/pry/helpers/text.rb +++ b/lib/pry/helpers/text.rb @@ -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 diff --git a/lib/pry/hooks.rb b/lib/pry/hooks.rb index 2c9ce925..9e61d0f5 100644 --- a/lib/pry/hooks.rb +++ b/lib/pry/hooks.rb @@ -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!" } diff --git a/lib/pry/indent.rb b/lib/pry/indent.rb index 6a1f94a2..16138dd3 100644 --- a/lib/pry/indent.rb +++ b/lib/pry/indent.rb @@ -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/ diff --git a/lib/pry/method.rb b/lib/pry/method.rb index b14bbe82..99eb086b 100644 --- a/lib/pry/method.rb +++ b/lib/pry/method.rb @@ -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`) diff --git a/lib/pry/pry_class.rb b/lib/pry/pry_class.rb index 575ee990..ecc9b573 100644 --- a/lib/pry/pry_class.rb +++ b/lib/pry/pry_class.rb @@ -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. diff --git a/lib/pry/wrapped_module.rb b/lib/pry/wrapped_module.rb index 5ea70ab5..2cf3174a 100644 --- a/lib/pry/wrapped_module.rb +++ b/lib/pry/wrapped_module.rb @@ -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