Prettify command descriptions, switches and stuff

Wrap command descriptions to 80 characters. Convert some string options
to symbols (where possible). Align options in code. Remove dots in the
end of switch descriptions.

Signed-off-by: Kyrylo Silin <kyrylosilin@gmail.com>

lib/pry/commands/amend_line.rb

@@ -6,13 +6,14 @@ class Pry
     command_options :interpolate => false, :listing => 'amend-line'
 
     banner <<-'BANNER'
-      Amend a line of input in multi-line mode. `amend-line N`, where the N in `amend-line N` represents line to replace.
+      Amend a line of input in multi-line mode. `amend-line N`, where the N represents
+      line to replace. Can also specify a range of lines using `amend-line N..M`
+      syntax. Passing "!" as replacement content deletes the line(s) instead.
 
-      Can also specify a range of lines using `amend-line N..M` syntax. Passing '!' as replacement content deletes the line(s) instead.
+      amend-line 1 puts 'new'    # replace line 1
-      e.g amend-line 1 puts 'hello world! # replace line 1'
+      amend-line 1..4 !          # delete lines 1..4
-      e.g amend-line 1..4 !               # delete lines 1..4
+      amend-line 3 >puts 'bye'   # insert before line 3
-      e.g amend-line 3 >puts 'goodbye'    # insert before line 3
+      amend-line puts 'appended' # no line number modifies immediately preceding line
-      e.g amend-line puts 'hello again'   # no line number modifies immediately preceding line
     BANNER
 
     def process

lib/pry/commands/bang.rb

@@ -2,10 +2,14 @@ class Pry
   class Command::Bang < Pry::ClassCommand
     match '!'
     group 'Editing'
-    description 'Clear the input buffer. Useful if the parsing process goes ' \
+    description 'Clear the input buffer.'
-      'wrong and you get stuck in the read loop.'
     command_options :use_prefix => false
 
+    banner <<-'BANNER'
+      Clear the input buffer. Useful if the parsing process goes wrong and you get
+      stuck in the read loop.
+    BANNER
+
     def process
       output.puts 'Input buffer cleared!'
       eval_string.replace('')

lib/pry/commands/bang_pry.rb

@@ -2,8 +2,11 @@ class Pry
   class Command::BangPry < Pry::ClassCommand
     match '!pry'
     group 'Navigating Pry'
-    description 'Start a Pry session on current self; this even works mid ' \
+    description 'Start a Pry session on current self.'
-      'multi-line expression.'
+
+    banner <<-'BANNER'
+      Start a Pry session on current self. Also works mid multi-line expression.
+    BANNER
 
     def process
       target.pry

lib/pry/commands/cat.rb

@@ -7,29 +7,28 @@ class Pry
 
     match 'cat'
     group 'Input and Output'
-    description "Show code from a file, Pry's input buffer, or the last " \
+    description "Show code from a file, Pry's input buffer, or the last exception."
-      "exception."
 
-    banner <<-USAGE
+    banner <<-'BANNER'
       Usage: cat FILE
              cat --ex [STACK_INDEX]
              cat --in [INPUT_INDEX_OR_RANGE]
 
-      cat is capable of showing part or all of a source file, the context of the
+      `cat` is capable of showing part or all of a source file, the context of the
       last exception, or an expression from Pry's input history.
 
-      cat --ex defaults to showing the lines surrounding the location of the last
+      `cat --ex` defaults to showing the lines surrounding the location of the last
-      exception. Invoking it more than once travels up the exception's backtrace,
+      exception. Invoking it more than once travels up the exception's backtrace, and
-      and providing a number shows the context of the given index of the backtrace.
+      providing a number shows the context of the given index of the backtrace.
-    USAGE
+    BANNER
 
     def options(opt)
-      opt.on :ex,        "Show the context of the last exception.", :optional_argument => true, :as => Integer
+      opt.on :ex,        "Show the context of the last exception", :optional_argument => true, :as => Integer
-      opt.on :i, :in,    "Show one or more entries from Pry's expression history.", :optional_argument => true, :as => Range, :default => -5..-1
+      opt.on :i, :in,    "Show one or more entries from Pry's expression history", :optional_argument => true, :as => Range, :default => -5..-1
-      opt.on :s, :start, "Starting line (defaults to the first line).", :optional_argument => true, :as => Integer
+      opt.on :s, :start, "Starting line (defaults to the first line)", :optional_argument => true, :as => Integer
-      opt.on :e, :end,   "Ending line (defaults to the last line).", :optional_argument => true, :as => Integer
+      opt.on :e, :end,   "Ending line (defaults to the last line)", :optional_argument => true, :as => Integer
-      opt.on :l, :'line-numbers', "Show line numbers."
+      opt.on :l, :'line-numbers', "Show line numbers"
-      opt.on :t, :type,  "The file type for syntax highlighting (e.g., 'ruby' or 'python').", :argument => true, :as => Symbol
+      opt.on :t, :type,  "The file type for syntax highlighting (e.g., 'ruby' or 'python')", :argument => true, :as => Symbol
     end
 
     def process

lib/pry/commands/cd.rb

@@ -4,18 +4,17 @@ class Pry
     group 'Context'
     description 'Move into a new context (object or scope).'
 
-    banner <<-BANNER
+    banner <<-'BANNER'
       Usage: cd [OPTIONS] [--help]
 
-      Move into new context (object or scope). As in unix shells use
+      Move into new context (object or scope). As in UNIX shells use `cd ..` to go
-      `cd ..` to go back, `cd /` to return to Pry top-level and `cd -`
+      back, `cd /` to return to Pry top-level and `cd -` to toggle between last two
-      to toggle between last two scopes).
+      scopes. Complex syntax (e.g `cd ../@x/y`) also supported.
-      Complex syntax (e.g `cd ../@x/y`) also supported.
 
-      e.g: `cd @x`
+      cd @x
-      e.g: `cd ..`
+      cd ..
-      e.g: `cd /`
+      cd /
-      e.g: `cd -`
+      cd -
 
       https://github.com/pry/pry/wiki/State-navigation#wiki-Changing_scope
     BANNER

lib/pry/commands/code_collector.rb

@@ -14,13 +14,15 @@ class Pry
 
     # Add the `--lines`, `-o`, `-i`, `-s`, `-d` options.
     def self.inject_options(opt)
-      opt.on :l, :lines, "Restrict to a subset of lines. Takes a line number or range.", :optional_argument => true, :as => Range, :default => 1..-1
+      opt.on :l, :lines, "Restrict to a subset of lines. Takes a line number or range",
-      opt.on :o, :out, "Select lines from Pry's output result history. Takes an index or range.", :optional_argument => true,
+                         :optional_argument => true, :as => Range, :default => 1..-1
-      :as => Range, :default => -5..-1
+      opt.on :o, :out,   "Select lines from Pry's output result history. Takes an index or range",
-      opt.on :i, :in, "Select lines from Pry's input expression history. Takes an index or range.", :optional_argument => true,
+                         :optional_argument => true, :as => Range, :default => -5..-1
-      :as => Range, :default => -5..-1
+      opt.on :i, :in,    "Select lines from Pry's input expression history. Takes an index or range",
-      opt.on :s, :super, "Select the 'super' method. Can be repeated to traverse the ancestors.", :as => :count
+                         :optional_argument => true, :as => Range, :default => -5..-1
-      opt.on :d, :doc, "Select lines from the code object's documentation."
+      opt.on :s, :super, "Select the 'super' method. Can be repeated to traverse the ancestors",
+                         :as => :count
+      opt.on :d, :doc,   "Select lines from the code object's documentation"
     end
 
     # The content (i.e code/docs) for the selected object.

lib/pry/commands/disable_pry.rb

@@ -4,15 +4,15 @@ class Pry
     group 'Navigating Pry'
     description 'Stops all future calls to pry and exits the current session.'
 
-    banner <<-BANNER
+    banner <<-'BANNER'
       Usage: disable-pry
 
-      After this command is run any further calls to pry will immediately return
+      After this command is run any further calls to pry will immediately return `nil`
-      `nil` without interrupting the flow of your program. This is particularly
+      without interrupting the flow of your program. This is particularly useful when
-      useful when you've debugged the problem you were having, and now wish the
+      you've debugged the problem you were having, and now wish the program to run to
-      program to run to the end.
+      the end.
 
-      As alternatives, consider using `exit!` to force the current ruby process
+      As alternatives, consider using `exit!` to force the current Ruby process
       to quit immediately; or using `edit-method -p` to remove the `binding.pry`
       from the code.
     BANNER

lib/pry/commands/edit.rb

@@ -14,31 +14,34 @@ class Pry
     group 'Editing'
     description 'Invoke the default editor on a file.'
 
-    banner <<-BANNER
+    banner <<-'BANNER'
       Usage: edit [--no-reload|--reload|--patch] [--line LINE] [--temp|--ex|FILE[:LINE]|OBJECT|--in N]
 
-      Open a text editor. When no FILE is given, edits the pry input buffer.
+      Open a text editor. When no FILE is given, edits the pry input buffer. Ensure
-      Ensure Pry.config.editor is set to your editor of choice.
+      `Pry.config.editor` is set to your editor of choice.
 
-      e.g: `edit sample.rb`
+      edit sample.rb
-      e.g: `edit sample.rb --line 105`
+      edit sample.rb --line 105
-      e.g: `edit MyClass#my_method`
+      edit MyClass#my_method
-      e.g: `edit -p MyClass#my_method`
+      edit -p MyClass#my_method
-      e.g: `edit YourClass`
+      edit YourClass
-      e.g: `edit --ex`
+      edit --ex`
 
       https://github.com/pry/pry/wiki/Editor-integration#wiki-Edit_command
     BANNER
 
     def options(opt)
-      opt.on :e, :ex, "Open the file that raised the most recent exception (_ex_.file)", :optional_argument => true, :as => Integer
+      opt.on :e, :ex,      "Open the file that raised the most recent exception (_ex_.file)",
-      opt.on :i, :in, "Open a temporary file containing the Nth input expression. N may be a range.", :optional_argument => true, :as => Range, :default => -1..-1
+                           :optional_argument => true, :as => Integer
+      opt.on :i, :in,      "Open a temporary file containing the Nth input expression. N may be a range",
+                           :optional_argument => true, :as => Range, :default => -1..-1
       opt.on :t, :temp,    "Open an empty temporary file"
-      opt.on :l, :line, "Jump to this line in the opened file", :argument => true, :as => Integer
+      opt.on :l, :line,    "Jump to this line in the opened file",
+                           :argument => true, :as => Integer
       opt.on :n, :"no-reload", "Don't automatically reload the edited code"
-      opt.on :c, :current, "Open the current __FILE__ and at __LINE__ (as returned by `whereami`)."
+      opt.on :c, :current, "Open the current __FILE__ and at __LINE__ (as returned by `whereami`)"
       opt.on :r, :reload,  "Reload the edited code immediately (default for ruby files)"
-      opt.on :p, :patch, "Instead of editing the object's file, try to edit in a tempfile and apply as a monkey patch."
+      opt.on :p, :patch,   "Instead of editing the object's file, try to edit in a tempfile and apply as a monkey patch"
     end
 
     def process

lib/pry/commands/exit.rb

@@ -2,25 +2,23 @@ class Pry
   class Command::Exit < Pry::ClassCommand
     match 'exit'
     group 'Navigating Pry'
-    description 'Pop the previous binding (does NOT exit program). Aliases: quit'
+    description 'Pop the previous binding.'
+    command_options :keep_retval => true
 
-    banner <<-BANNER
+    banner <<-'BANNER'
       Usage:   exit [OPTIONS] [--help]
       Aliases: quit
 
-      It can be useful to exit a context with a user-provided value. For
+      Pop the previous binding (does NOT exit program). It can be useful to exit a
-      instance an exit value can be used to determine program flow.
+      context with a user-provided value. For instance an exit value can be used to
+      determine program flow.
 
-      e.g: `exit "pry this"`
+      exit "pry this"
-      e.g: `exit`
+      exit
 
       https://github.com/pry/pry/wiki/State-navigation#wiki-Exit_with_value
     BANNER
 
-    command_options(
-                    :keep_retval => true
-                    )
-
     def process
       if _pry_.binding_stack.one?
         _pry_.run_command "exit-all #{arg_string}"

lib/pry/commands/exit_all.rb

@@ -2,8 +2,15 @@ class Pry
   class Command::ExitAll < Pry::ClassCommand
     match 'exit-all'
     group 'Navigating Pry'
-    description 'End the current Pry session (popping all bindings) and ' \
+    description 'End the current Pry session.'
-      'returning to caller. Accepts optional return value. Aliases: !!@'
+
+    banner <<-'BANNER'
+      Usage:   exit-all [--help]
+      Aliases: !!@
+
+      End the current Pry session (popping all bindings and returning to caller).
+      Accepts optional return value.
+    BANNER
 
     def process
       # calculate user-given value

lib/pry/commands/exit_program.rb

@@ -2,7 +2,15 @@ class Pry
   class Command::ExitProgram < Pry::ClassCommand
     match 'exit-program'
     group 'Navigating Pry'
-    description 'End the current program. Aliases: quit-program, !!!'
+    description 'End the current program.'
+
+    banner <<-'BANNER'
+      Usage:   exit-program [--help]
+      Aliases: quit-program
+               !!!
+
+      End the current program.
+    BANNER
 
     def process
       Pry.save_history if Pry.config.history.should_save

lib/pry/commands/find_method.rb

@@ -4,20 +4,26 @@ class Pry
 
     match 'find-method'
     group 'Context'
-    options :requires_gem => 'ruby18_source_location' if mri_18?
+    description 'Recursively search for a method within a Class/Module or the current namespace.'
-    options :shellwords => false
+    command_options :shellwords => false
+    command_options :requires_gem => 'ruby18_source_location' if mri_18?
 
-    description 'Recursively search for a method within a Class/Module or the current namespace. find-method [-n | -c] METHOD [NAMESPACE]'
 
-    banner <<-BANNER
+    banner <<-'BANNER'
       Usage: find-method  [-n|-c] METHOD [NAMESPACE]
 
       Recursively search for a method within a Class/Module or the current namespace.
-      Use the `-n` switch (the default) to search for methods whose name matches the given regex.
+      Use the `-n` switch (the default) to search for methods whose name matches the
-      Use the `-c` switch to search for methods that contain the given code.
+      given regex. Use the `-c` switch to search for methods that contain the given
+      code.
 
-      e.g find-method re Pry                # find all methods whose name match /re/ inside the Pry namespace. Matches Pry#repl, etc.
+      # Find all methods whose name match /re/ inside
-      e.g find-method -c 'output.puts' Pry  # find all methods that contain the code: output.puts inside the Pry namepsace.
+      # the Pry namespace. Matches Pry#repl, etc.
+      find-method re Pry
+
+      # Find all methods that contain the code:
+      # output.puts inside the Pry namepsace.
+      find-method -c 'output.puts' Pry
     BANNER
 
     def setup

lib/pry/commands/gem_cd.rb

@@ -5,10 +5,11 @@ class Pry
     description "Change working directory to specified gem's directory."
     command_options :argument_required => true
 
-    banner <<-BANNER
+    banner <<-'BANNER'
       Usage: gem-cd GEM_NAME
 
-      Change the current working directory to that in which the given gem is installed.
+      Change the current working directory to that in which the given gem is
+      installed.
     BANNER
 
     def process(gem)

lib/pry/commands/gem_install.rb

@@ -5,10 +5,13 @@ class Pry
     description 'Install a gem and refresh the gem cache.'
     command_options :argument_required => true
 
-    banner <<-BANNER
+    banner <<-'BANNER'
       Usage: gem-install GEM_NAME
 
-      Installs the given gem and refreshes the gem cache so that you can immediately 'require GEM_FILE'
+      Installs the given gem and refreshes the gem cache so that you can immediately
+      'require GEM_FILE'.
+
+      gem-install pry-stack_explorer
     BANNER
 
     def setup

lib/pry/commands/gem_list.rb

@@ -4,11 +4,11 @@ class Pry
     group 'Gems'
     description 'List and search installed gems.'
 
-    banner <<-BANNER
+    banner <<-'BANNER'
       Usage: gem-list [REGEX]
 
-      List all installed gems, when a regex is provided, limit the output to those that
+      List all installed gems, when a regex is provided, limit the output to those
-      match the regex.
+      that match the regex.
     BANNER
 
     def process(pattern = nil)

lib/pry/commands/gem_open.rb

@@ -5,11 +5,13 @@ class Pry
     description 'Opens the working directory of the gem in your editor'
     command_options :argument_required => true
 
-    banner <<-BANNER
+    banner <<-'BANNER'
       Usage: gem-open GEM_NAME
 
-      Change the current working directory to that in which the given gem is installed,
+      Change the current working directory to that in which the given gem is
-      and then opens your text editor.
+      installed, and then opens your text editor.
+
+      gem-open pry-exception_explorer
     BANNER
 
     def process(gem)

lib/pry/commands/gist.rb

@@ -36,14 +36,15 @@ class Pry
     description Pry::Gist::DESCRIPTION
     command_options :requires_gem => 'jist', :shellwords => false
 
-    banner <<-USAGE
+    banner <<-BANNER
       Usage: gist [options]
+
       #{Pry::Gist::DESCRIPTION}
 
-      If you'd like to associate your gists with your GitHub account, run:
+      If you would like to associate your gists with your GitHub account, run
-          gist --login
+      `gist --login`.
 
-    USAGE
+    BANNER
     banner << Pry::Gist.examples_docs << "\n"
 
     attr_accessor :content, :filename
@@ -61,24 +62,24 @@ class Pry
     def options(opt)
       ext ='ruby'
       opt.on :login, "Authenticate the jist gem with GitHub"
-      opt.on :d, :doc, "Gist a method's documentation.", :argument => true do |meth_name|
+      opt.on :d, :doc, "Gist a method's documentation", :argument => true do |meth_name|
         meth = get_method_or_raise(meth_name, target, {})
         text.no_color do
           @content << process_comment_markup(meth.doc) << "\n"
         end
         @filename = meth.source_file + ".doc"
       end
-      opt.on :m, :method, "Gist a method's source.", :argument => true do |meth_name|
+      opt.on :m, :method, "Gist a method's source", :argument => true do |meth_name|
         from_pry_api get_method_or_raise(meth_name, target, {})
       end
-      opt.on :k, :command, "Gist a command's source.", :argument => true do |command_name|
+      opt.on :k, :command, "Gist a command's source", :argument => true do |command_name|
         command = find_command(command_name)
         from_pry_api Pry::Method.new(command.block)
       end
-      opt.on :c, :class, "Gist a class or module's source.", :argument => true do |class_name|
+      opt.on :c, :class, "Gist a class or module's source", :argument => true do |class_name|
         from_pry_api Pry::WrappedModule.from_str(class_name, target)
       end
-      opt.on :var, "Gist a variable's content.", :argument => true do |variable_name|
+      opt.on :var, "Gist a variable's content", :argument => true do |variable_name|
         begin
           obj = target.eval(variable_name)
         rescue Pry::RescuableException
@@ -87,7 +88,7 @@ class Pry
 
         @content << Pry.config.gist.inspecter.call(obj) << "\n"
       end
-      opt.on :hist, "Gist a range of Readline history lines.",  :optional_argument => true, :as => Range, :default => -20..-1 do |range|
+      opt.on :hist, "Gist a range of Readline history lines",  :optional_argument => true, :as => Range, :default => -20..-1 do |range|
         h = Pry.history.to_a
         @content << h[one_index_range(convert_to_range(range))].join("\n") << "\n"
       end
@@ -96,7 +97,7 @@ class Pry
         @content << File.read(File.expand_path(file)) << "\n"
         @filename = file
       end
-      opt.on :o, :out, "Gist entries from Pry's output result history. Takes an index or range.", :optional_argument => true,
+      opt.on :o, :out, "Gist entries from Pry's output result history. Takes an index or range", :optional_argument => true,
       :as => Range, :default => -1 do |range|
         range = convert_to_range(range)
 
@@ -106,10 +107,10 @@ class Pry
 
         @content << "\n"
       end
-      opt.on :clip, "Copy the selected content to clipboard instead, do NOT gist it.", :default => false
+      opt.on :clip, "Copy the selected content to clipboard instead, do NOT gist it", :default => false
       opt.on :p, :public, "Create a public gist (default: false)", :default => false
-      opt.on :l, :lines, "Only gist a subset of lines from the gistable content.", :optional_argument => true, :as => Range, :default => 1..-1
+      opt.on :l, :lines, "Only gist a subset of lines from the gistable content", :optional_argument => true, :as => Range, :default => 1..-1
-      opt.on :i, :in, "Gist entries from Pry's input expression history. Takes an index or range.", :optional_argument => true,
+      opt.on :i, :in, "Gist entries from Pry's input expression history. Takes an index or range", :optional_argument => true,
       :as => Range, :default => -1 do |range|
         range = convert_to_range(range)
         input_expressions = _pry_.input_array[range] || []

lib/pry/commands/help.rb

@@ -2,15 +2,14 @@ class Pry
   class Command::Help < Pry::ClassCommand
     match 'help'
     group 'Help'
-    description 'Show a list of commands. Type `help <foo>` for information about <foo>.'
+    description 'Show a list of commands or information about a specific command'
 
-    banner <<-BANNER
+    banner <<-'BANNER'
       Usage: help [COMMAND]
 
       With no arguments, help lists all the available commands in the current
-      command-set along with their description.
+      command-set along with their description. When given a command name as an
-
+      argument, shows the help for that command.
-      When given a command name as an argument, shows the help for that command.
     BANNER
 
     # We only want to show commands that have descriptions, so that the

lib/pry/commands/hist.rb

@@ -2,10 +2,10 @@ class Pry
   class Command::Hist < Pry::ClassCommand
     match 'hist'
     group 'Editing'
-    description 'Show and replay Readline history. Aliases: history'
+    description 'Show and replay Readline history.'
 
-    banner <<-USAGE
+    banner <<-'BANNER'
-      Usage: hist
+      Usage:   hist [--head|--tail]
                hist --head N
                hist --tail N
                hist --show START..END
@@ -13,20 +13,22 @@ class Pry
                hist --clear
                hist --replay START..END
                hist --save [START..END] FILE
-    USAGE
+      Aliases: history
+
+      Show and replay Readline history.
+    BANNER
 
     def options(opt)
-      opt.on :H, :head, "Display the first N items.", :optional_argument => true, :as => Integer
+      opt.on :H, :head,   "Display the first N items", :optional_argument => true, :as => Integer
-      opt.on :T, :tail, "Display the last N items.", :optional_argument => true, :as => Integer
+      opt.on :T, :tail,   "Display the last N items", :optional_argument => true, :as => Integer
-      opt.on :s, :show, "Show the given range of lines.", :optional_argument => true, :as => Range
+      opt.on :s, :show,   "Show the given range of lines", :optional_argument => true, :as => Range
-      opt.on :G, :grep, "Show lines matching the given pattern.", :argument => true, :as => String
+      opt.on :G, :grep,   "Show lines matching the given pattern", :argument => true, :as => String
-      opt.on :c, :clear, "Clear the current session's history."
+      opt.on :c, :clear , "Clear the current session's history"
-      opt.on :r, :replay, "Replay a line or range of lines.", :argument => true, :as => Range
+      opt.on :r, :replay, "Replay a line or range of lines", :argument => true, :as => Range
-      opt.on     :save, "Save history to a file.", :argument => true, :as => Range
+      opt.on     :save,   "Save history to a file", :argument => true, :as => Range
-
+      opt.on :e, :'exclude-pry', "Exclude Pry commands from the history"
-      opt.on :e, :'exclude-pry', "Exclude Pry commands from the history."
+      opt.on :n, :'no-numbers',  "Omit line numbers"
-      opt.on :n, :'no-numbers', "Omit line numbers."
+      opt.on :f, :flood,         "Do not use a pager to view text longer than one screen"
-      opt.on :f, :flood, "Do not use a pager to view text longer than one screen."
     end
 
     def process

lib/pry/commands/import_set.rb

@@ -6,6 +6,10 @@ class Pry
     # of this command.
     description 'Import a Pry command set.'
 
+    banner <<-'BANNER'
+      Import a Pry command set.
+    BANNER
+
     def process(command_set_name)
       raise CommandError, "Provide a command set name" if command_set.nil?
 

lib/pry/commands/install_command.rb

@@ -4,7 +4,7 @@ class Pry
     group 'Commands'
     description 'Install a disabled command.'
 
-    banner <<-BANNER
+    banner <<-'BANNER'
       Usage: install-command COMMAND
 
       Installs the gems necessary to run the given COMMAND. You will generally not

lib/pry/commands/jump_to.rb

@@ -2,8 +2,11 @@ class Pry
   class Command::JumpTo < Pry::ClassCommand
     match 'jump-to'
     group 'Navigating Pry'
-    description 'Jump to a binding further up the stack, popping all ' \
+    description 'Jump to a binding further up the stack.'
-      'bindings below.'
+
+    banner <<-'BANNER'
+      Jump to a binding further up the stack, popping all bindings below.
+    BANNER
 
     def process(break_level)
       break_level = break_level.to_i

lib/pry/commands/ls.rb

@@ -96,33 +96,36 @@ class Pry
     command_options :shellwords => false, :interpolate => false
 
     def options(opt)
-      opt.banner unindent <<-USAGE
+      opt.banner unindent <<-'BANNER'
         Usage: ls [-m|-M|-p|-pM] [-q|-v] [-c|-i] [Object]
                ls [-g] [-l]
 
-        ls shows you which methods, constants and variables are accessible to Pry. By default it shows you the local variables defined in the current shell, and any public methods or instance variables defined on the current object.
+        ls shows you which methods, constants and variables are accessible to Pry. By
+        default it shows you the local variables defined in the current shell, and any
+        public methods or instance variables defined on the current object.
 
-        The colours used are configurable using Pry.config.ls.*_color, and the separator is Pry.config.ls.separator.
+        The colours used are configurable using Pry.config.ls.*_color, and the separator
+        is Pry.config.ls.separator.
 
-        Pry.config.ls.ceiling is used to hide methods defined higher up in the inheritance chain, this is by default set to [Object, Module, Class] so that methods defined on all Objects are omitted. The -v flag can be used to ignore this setting and show all methods, while the -q can be used to set the ceiling much lower and show only methods defined on the object or its direct class.
+        Pry.config.ls.ceiling is used to hide methods defined higher up in the
-      USAGE
+        inheritance chain, this is by default set to [Object, Module, Class] so that
+        methods defined on all Objects are omitted. The -v flag can be used to ignore
+        this setting and show all methods, while the -q can be used to set the ceiling
+        much lower and show only methods defined on the object or its direct class.
+      BANNER
 
-      opt.on :m, "methods", "Show public methods defined on the Object (default)"
+      opt.on :m, :methods,   "Show public methods defined on the Object (default)"
       opt.on :M, "instance-methods", "Show methods defined in a Module or Class"
+      opt.on :p, :ppp,       "Show public, protected (in yellow) and private (in green) methods"
+      opt.on :q, :quiet,     "Show only methods defined on object.singleton_class and object.class"
+      opt.on :v, :verbose,   "Show methods and constants on all super-classes (ignores Pry.config.ls.ceiling)"
+      opt.on :g, :globals,   "Show global variables, including those builtin to Ruby (in cyan)"
+      opt.on :l, :locals,    "Show hash of local vars, sorted by descending size"
+      opt.on :c, :constants, "Show constants, highlighting classes (in blue), and exceptions (in purple).\n" +
+      " " * 32 +             "Constants that are pending autoload? are also shown (in yellow)"
+      opt.on :i, :ivars,     "Show instance variables (in blue) and class variables (in bright blue)"
+      opt.on :G, :grep,      "Filter output by regular expression", :argument => true
 
-      opt.on :p, "ppp", "Show public, protected (in yellow) and private (in green) methods"
-      opt.on :q, "quiet", "Show only methods defined on object.singleton_class and object.class"
-      opt.on :v, "verbose", "Show methods and constants on all super-classes (ignores Pry.config.ls.ceiling)"
-
-      opt.on :g, "globals", "Show global variables, including those builtin to Ruby (in cyan)"
-      opt.on :l, "locals", "Show hash of local vars, sorted by descending size"
-
-      opt.on :c, "constants", "Show constants, highlighting classes (in blue), and exceptions (in purple).\n" +
-      " " * 32 +              "Constants that are pending autoload? are also shown (in yellow)."
-
-      opt.on :i, "ivars", "Show instance variables (in blue) and class variables (in bright blue)"
-
-      opt.on :G, "grep", "Filter output by regular expression", :argument => true
       if jruby?
         opt.on :J, "all-java", "Show all the aliases for methods from java (default is to show only prettiest)"
       end

lib/pry/commands/nesting.rb

@@ -4,6 +4,10 @@ class Pry
     group 'Navigating Pry'
     description 'Show nesting information.'
 
+    banner <<-'BANNER'
+      Show nesting information.
+    BANNER
+
     def process
       output.puts 'Nesting status:'
       output.puts '--'

lib/pry/commands/play.rb

@@ -4,17 +4,17 @@ class Pry
     group 'Editing'
     description 'Playback a string variable or a method or a file as input.'
 
-    banner <<-BANNER
+    banner <<-'BANNER'
       Usage: play [OPTIONS] [--help]
 
-      The play command enables you to replay code from files and methods as
+      The play command enables you to replay code from files and methods as if they
-      if they were entered directly in the Pry REPL. Default action (no
+      were entered directly in the Pry REPL. Default action (no options) is to play
-      options) is to play the provided string variable.
+      the provided string variable.
 
-      e.g: `play --lines 149..153`
+      play --lines 149..153
-      e.g: `play -i 20 --lines 1..3`
+      play -i 20 --lines 1..3
-      e.g: `play Pry#repl --lines 1..-1`
+      play Pry#repl --lines 1..-1
-      e.g: `play Rakefile --lines 5`
+      play Rakefile --lines 5
 
       https://github.com/pry/pry/wiki/User-Input#wiki-Play
     BANNER
@@ -22,7 +22,9 @@ class Pry
     def options(opt)
       CodeCollector.inject_options(opt)
 
-      opt.on :open, "open", 'When used with the -m switch, it plays the entire method except the last line, leaving the method definition "open". `amend-line` can then be used to modify the method.'
+      opt.on :open, 'When used with the -m switch, it plays the entire method except' \
+                    ' the last line, leaving the method definition "open". `amend-line`' \
+                    ' can then be used to modify the method.'
     end
 
     def process

lib/pry/commands/pry_backtrace.rb

@@ -7,14 +7,13 @@ class Pry
     banner <<-BANNER
       Usage: pry-backtrace [OPTIONS] [--help]
 
-      Show the backtrace for the position in the code where Pry was started. This can be used to
+      Show the backtrace for the position in the code where Pry was started. This can
-      infer the behavior of the program immediately before it entered Pry, just like the backtrace
+      be used to infer the behavior of the program immediately before it entered Pry,
-      property of an exception.
+      just like the backtrace property of an exception.
 
-      (NOTE: if you are looking for the backtrace of the most recent exception raised,
+      NOTE: if you are looking for the backtrace of the most recent exception raised,
-      just type: `_ex_.backtrace` instead, see https://github.com/pry/pry/wiki/Special-Locals)
+      just type: `_ex_.backtrace` instead.
-
+      See: https://github.com/pry/pry/wiki/Special-Locals
-      e.g: pry-backtrace
     BANNER
 
     def process

lib/pry/commands/pry_version.rb

@@ -4,6 +4,10 @@ class Pry
     group 'Misc'
     description 'Show Pry version.'
 
+    banner <<-'BANNER'
+      Show Pry version.
+    BANNER
+
     def process
       output.puts "Pry version: #{Pry::VERSION} on Ruby #{RUBY_VERSION}."
     end

lib/pry/commands/raise_up.rb

@@ -7,15 +7,18 @@ class Pry
     command_options :listing => 'raise-up'
 
     banner <<-BANNER
-      Raise up, like exit, allows you to quit pry. Instead of returning a value however, it raises an exception.
+      Raise up, like exit, allows you to quit pry. Instead of returning a value
-      If you don't provide the exception to be raised, it will use the most recent exception (in pry _ex_).
+      however, it raises an exception. If you don't provide the exception to be
+      raised, it will use the most recent exception (in pry `_ex_`).
 
-      e.g. `raise-up "get-me-out-of-here"` is equivalent to:
+      When called as raise-up! (with an exclamation mark), this command raises the
-           `raise "get-me-out-of-here"
+      exception through any nested prys you have created by "cd"ing into objects.
-            raise-up`
 
-      When called as raise-up! (with an exclamation mark), this command raises the exception through
+      raise-up "get-me-out-of-here"
-      any nested prys you have created by "cd"ing into objects.
+
+      # This is equivalent to the command above.
+      raise "get-me-out-of-here"
+      raise-up
     BANNER
 
     def process

lib/pry/commands/reload_code.rb

@@ -2,7 +2,11 @@ class Pry
   class Command::ReloadCode < Pry::ClassCommand
     match 'reload-code'
     group 'Misc'
-    description 'Reload the source file that contains the specified code object'
+    description 'Reload the source file that contains the specified code object.'
+
+    banner <<-'BANNER'
+      Reload the source file that contains the specified code object.
+    BANNER
 
     def process
       code_object = Pry::CodeObject.lookup(obj_name, target, _pry_)

lib/pry/commands/reset.rb

@@ -4,6 +4,10 @@ class Pry
     group 'Context'
     description 'Reset the REPL to a clean state.'
 
+    banner <<-'BANNER'
+      Reset the REPL to a clean state.
+    BANNER
+
     def process
       output.puts 'Pry reset.'
       exec 'pry'

lib/pry/commands/ri.rb

@@ -2,13 +2,15 @@ class Pry
   class Command::Ri < Pry::ClassCommand
     match 'ri'
     group 'Introspection'
-    description 'View ri documentation. e.g `ri Array#each`'
+    description 'View ri documentation.'
 
-    banner <<-BANNER
+    banner <<-'BANNER'
       Usage: ri [spec]
-      e.g. ri Array#each
 
-      Relies on the rdoc gem being installed. See also: show-doc.
+      View ri documentation. Relies on the "rdoc" gem being installed.
+      See also "show-doc" command.
+
+      ri Array#each
     BANNER
 
     def process(spec)

lib/pry/commands/save_file.rb

@@ -6,20 +6,22 @@ class Pry
     group 'Input and Output'
     description 'Export to a file using content from the REPL.'
 
-    banner <<-USAGE
+    banner <<-'BANNER'
       Usage: save-file [OPTIONS] [FILE]
-      Save REPL content to a file.
+
-      e.g: save-file my_method ./hello.rb
+      Export to a file using content from the REPL.
-      e.g: save-file -i 1..10 ./hello.rb --append
+
-      e.g: save-file show-method ./my_command.rb
+      save-file my_method ./hello.rb
-      e.g: save-file sample_file.rb --lines 2..10 ./output_file.rb
+      save-file -i 1..10 ./hello.rb --append
-    USAGE
+      save-file show-method ./my_command.rb
+      save-file sample_file.rb --lines 2..10 ./output_file.rb
+    BANNER
 
     def options(opt)
       CodeCollector.inject_options(opt)
 
-      opt.on :to=, "Select where content is to be saved."
+      opt.on :to=,        "Select where content is to be saved"
-      opt.on :a, :append, "Append output to file."
+      opt.on :a, :append, "Append output to file"
     end
 
     def process

lib/pry/commands/shell_command.rb

@@ -6,6 +6,15 @@ class Pry
     command_options :listing => '.<shell command>', :use_prefix => false,
       :takes_block => true
 
+    banner <<-'BANNER'
+      Usage: .COMMAND_NAME
+
+      All text following a "." is forwarded to the shell.
+
+      .ls -aF
+      .uname
+    BANNER
+
     def process(cmd)
       if cmd =~ /^cd\s+(.+)/i
         dest = $1

lib/pry/commands/shell_mode.rb

@@ -4,6 +4,10 @@ class Pry
     group 'Input and Output'
     description 'Toggle shell mode. Bring in pwd prompt and file completion.'
 
+    banner <<-'BANNER'
+      Toggle shell mode. Bring in pwd prompt and file completion.
+    BANNER
+
     def process
       case _pry_.prompt
       when Pry::SHELL_PROMPT

lib/pry/commands/show_command.rb

@@ -4,15 +4,19 @@ class Pry
     group 'Introspection'
     description 'Show the source for CMD.'
 
+    banner <<-'BANNER'
+      Show the source for CMD.
+    BANNER
+
     def process(*args)
       target = target()
 
       opts = Slop.parse!(args) do |opt|
-        opt.banner unindent <<-USAGE
+        opt.banner unindent <<-'BANNER'
           NOTE: show-command is DEPRECATED. Use show-source [command_name] instead.
-        USAGE
+        BANNER
 
-        opt.on :h, :help, "This message." do
+        opt.on :h, :help, "This message" do
           output.puts opt.help
         end
       end

lib/pry/commands/show_doc.rb

@@ -6,16 +6,18 @@ class Pry
 
     match 'show-doc'
     group 'Introspection'
-    description 'Show the documentation for a method or class. Aliases: \?'
+    description 'Show the documentation for a method or class.'
 
     banner <<-BANNER
       Usage:   show-doc [OPTIONS] [METH]
       Aliases: ?
 
-      Show the documentation for a method or class. Tries instance methods first and then methods by default.
+      Show the documentation for a method or class. Tries instance methods first and
-      e.g show-doc hello_method    # docs for hello_method
+      then methods by default.
-      e.g show-doc Pry             # docs for Pry class
+
-      e.g show-doc Pry -a          # docs for all definitions of Pry class (all monkey patches)
+      show-doc hi_method # docs for hi_method
+      show-doc Pry       # for Pry class
+      show-doc Pry -a    # for all definitions of Pry class (all monkey patches)
     BANNER
 
     # The docs for code_object prepared for display.

lib/pry/commands/show_info.rb

@@ -2,18 +2,18 @@ class Pry
   class Command::ShowInfo < Pry::ClassCommand
     extend Pry::Helpers::BaseHelpers
 
-    options :shellwords => false
+    command_options :shellwords => false
-    options :requires_gem => "ruby18_source_location" if mri_18?
+    command_options :requires_gem => "ruby18_source_location" if mri_18?
 
     def setup
       require 'ruby18_source_location' if mri_18?
     end
 
     def options(opt)
-      opt.on :s, :super, "Select the 'super' method. Can be repeated to traverse the ancestors.", :as => :count
+      opt.on :s, :super, "Select the 'super' method. Can be repeated to traverse the ancestors", :as => :count
-      opt.on :l, "line-numbers", "Show line numbers."
+      opt.on :l, "line-numbers", "Show line numbers"
-      opt.on :b, "base-one", "Show line numbers but start numbering at 1 (useful for `amend-line` and `play` commands)."
+      opt.on :b, "base-one", "Show line numbers but start numbering at 1 (useful for `amend-line` and `play` commands)"
-      opt.on :f, :flood, "Do not use a pager to view text longer than one screen."
+      opt.on :f, :flood, "Do not use a pager to view text longer than one screen"
       opt.on :a, :all,   "Show all definitions and monkeypatches of the module/class"
     end
 

lib/pry/commands/show_input.rb

@@ -4,6 +4,10 @@ class Pry
     group 'Editing'
     description 'Show the contents of the input buffer for the current multi-line expression.'
 
+    banner <<-'BANNER'
+      Show the contents of the input buffer for the current multi-line expression.
+    BANNER
+
     def process
       output.puts Code.new(eval_string).with_line_numbers
     end

lib/pry/commands/show_source.rb

@@ -4,20 +4,21 @@ class Pry
   class Command::ShowSource < Command::ShowInfo
     match 'show-source'
     group 'Introspection'
-    description 'Show the source for a method or class. Aliases: $, show-method'
+    description 'Show the source for a method or class.'
 
-    banner <<-BANNER
+    banner <<-'BANNER'
       Usage:   show-source [OPTIONS] [METH|CLASS]
       Aliases: $, show-method
 
-      Show the source for a method or class. Tries instance methods first and then methods by default.
+      Show the source for a method or class. Tries instance methods first and then
+      methods by default.
 
-      e.g: `show-source hello_method`
+      show-source hi_method
-      e.g: `show-source hello_method`
+      show-source hi_method
-      e.g: `show-source Pry#rep`         # source for Pry#rep method
+      show-source Pry#rep     # source for Pry#rep method
-      e.g: `show-source Pry`             # source for Pry class
+      show-source Pry         # for Pry class
-      e.g: `show-source Pry -a`          # source for all Pry class definitions (all monkey patches)
+      show-source Pry -a      # for all Pry class definitions (all monkey patches)
-      e.g: `show-source Pry --super      # source for superclass of Pry (Object class)
+      show-source Pry --super # for superclass of Pry (Object class)
 
       https://github.com/pry/pry/wiki/Source-browsing#wiki-Show_method
     BANNER

lib/pry/commands/simple_prompt.rb

@@ -4,6 +4,10 @@ class Pry
     group 'Misc'
     description 'Toggle the simple prompt.'
 
+    banner <<-'BANNER'
+      Toggle the simple prompt.
+    BANNER
+
     def process
       case _pry_.prompt
       when Pry::SIMPLE_PROMPT

lib/pry/commands/stat.rb

@@ -5,10 +5,12 @@ class Pry
     description 'View method information and set _file_ and _dir_ locals.'
     command_options :shellwords => false
 
-    banner <<-BANNER
+    banner <<-'BANNER'
         Usage: stat [OPTIONS] [METH]
+
         Show method information for method METH and set _file_ and _dir_ locals.
-        e.g: stat hello_method
+
+        stat hello_method
     BANNER
 
     def options(opt)

lib/pry/commands/switch_to.rb

@@ -2,8 +2,11 @@ class Pry
   class Command::SwitchTo < Pry::ClassCommand
     match 'switch-to'
     group 'Navigating Pry'
-    description 'Start a new subsession on a binding in the current stack ' \
+    description 'Start a new subsession on a binding in the current stack.'
-      '(numbered by nesting).'
+
+    banner <<-'BANNER'
+      Start a new subsession on a binding in the current stack (numbered by nesting).
+    BANNER
 
     def process(selection)
       selection = selection.to_i

lib/pry/commands/toggle_color.rb

@@ -4,6 +4,12 @@ class Pry
     group 'Misc'
     description 'Toggle syntax highlighting.'
 
+    banner <<-'BANNER'
+      Usage: toggle-color
+
+      Toggle syntax highlighting.
+    BANNER
+
     def process
       Pry.color = !Pry.color
       output.puts "Syntax highlighting #{Pry.color ? "on" : "off"}"

lib/pry/commands/whereami.rb

@@ -4,25 +4,24 @@ class Pry
     description 'Show code surrounding the current context.'
     group 'Context'
 
-    banner <<-BANNER
+    banner <<-'BANNER'
       Usage: whereami [-qn] [N]
 
-      Describe the current location. If you use `binding.pry` inside a
+      Describe the current location. If you use `binding.pry` inside a method then
-      method then whereami will print out the source for that method.
+      whereami will print out the source for that method.
 
-      If a number is passed, then N lines before and after the current line
+      If a number is passed, then N lines before and after the current line will be
-      will be shown instead of the method itself.
+      shown instead of the method itself.
 
-      The `-q` flag can be used to suppress error messages in the case that
+      The `-q` flag can be used to suppress error messages in the case that there's
-      there's no code to show. This is used by pry in the default
+      no code to show. This is used by pry in the default before_session hook to show
-      before_session hook to show you when you arrive at a `binding.pry`.
+      you when you arrive at a `binding.pry`.
 
       The `-n` flag can be used to hide line numbers so that code can be copy/pasted
       effectively.
 
-      When pry was started on an Object and there is no associated method,
+      When pry was started on an Object and there is no associated method, whereami
-      whereami will instead output a brief description of the current
+      will instead output a brief description of the current object.
-      object.
     BANNER
 
     def setup
@@ -33,7 +32,7 @@ class Pry
 
     def options(opt)
       opt.on :q, :quiet,             "Don't display anything in case of an error"
-      opt.on :n, :"no-line-numbers", "Do not display line numbers."
+      opt.on :n, :"no-line-numbers", "Do not display line numbers"
     end
 
     def code

lib/pry/commands/wtf.rb

@@ -2,27 +2,25 @@ class Pry
   class Command::Wtf < Pry::ClassCommand
     match /wtf([?!]*)/
     group 'Context'
-    description 'Show the backtrace of the most recent exception'
+    description 'Show the backtrace of the most recent exception.'
     options :listing => 'wtf?'
 
-    banner <<-BANNER
+    banner <<-'BANNER'
+      Usage: wtf[?|!]
+
       Show's a few lines of the backtrace of the most recent exception (also available
-      as _ex_.backtrace).
+      as `_ex_.backtrace`). If you want to see more lines, add more question marks or
+      exclamation marks.
 
-      If you want to see more lines, add more question marks or exclamation marks:
+      wtf?
+      wtf?!???!?!?
 
-      e.g.
+      # To see the entire backtrace, pass the `-v` or `--verbose` flag.
-      pry(main)> wtf?
+      wtf -v
-      pry(main)> wtf?!???!?!?
-
-      To see the entire backtrace, pass the -v/--verbose flag:
-
-      e.g.
-      pry(main)> wtf -v
     BANNER
 
     def options(opt)
-      opt.on(:v, :verbose, "Show the full backtrace.")
+      opt.on :v, :verbose, "Show the full backtrace"
     end
 
     def process

spec/commands/show_source_spec.rb

@@ -21,7 +21,7 @@ if !PryTestHelpers.mri18_and_no_real_source_location?
     end
 
     it "should output help" do
-      pry_eval('show-source -h').should =~ /Usage: show-source/
+      pry_eval('show-source -h').should =~ /Usage:\s+show-source/
     end
 
     it "should output a method's source with line numbers" do