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>, 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<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
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 <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]+$/, '')
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