diff --git a/.rubocop_todo.yml b/.rubocop_todo.yml
index 0919b867..2269ccf7 100644
--- a/.rubocop_todo.yml
+++ b/.rubocop_todo.yml
@@ -420,6 +420,7 @@ Layout/SpaceInsideStringInterpolation:
     - 'lib/pry/commands/ls/methods.rb'
     - 'lib/pry/commands/ls/self_methods.rb'
     - 'lib/pry/commands/show_doc.rb'
+    - 'lib/pry/commands/show_source.rb'
     - 'lib/pry/commands/stat.rb'
     - 'spec/commands/edit_spec.rb'
     - 'spec/history_spec.rb'
@@ -523,7 +524,7 @@ Metrics/AbcSize:
 # Configuration parameters: CountComments, ExcludedMethods.
 # ExcludedMethods: refine
 Metrics/BlockLength:
-  Max: 716
+  Max: 731
 
 # Offense count: 1
 # Configuration parameters: CountBlocks.
@@ -1378,6 +1379,7 @@ Style/UnneededCondition:
   Exclude:
     - 'lib/pry/command.rb'
     - 'lib/pry/commands/show_doc.rb'
+    - 'lib/pry/commands/show_source.rb'
     - 'lib/pry/commands/stat.rb'
 
 # Offense count: 5
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3dc7bff6..37b0bf14 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,4 +1,7 @@
-### HEAD
+### master
+
+* Deprecated the `show-doc` command. The `show-source -d` is the new recommended
+  way of reading docs ([#1934](https://github.com/pry/pry/pull/1934))
 
 ### [v0.12.2][v0.12.2] (November 12, 2018)
 
diff --git a/lib/pry/commands/show_doc.rb b/lib/pry/commands/show_doc.rb
index 978a3a3e..0a3cdd22 100644
--- a/lib/pry/commands/show_doc.rb
+++ b/lib/pry/commands/show_doc.rb
@@ -20,6 +20,16 @@ class Pry
       show-doc Pry -a    # for all definitions of Pry class (all monkey patches)
     BANNER
 
+    def process
+      super
+
+      output.puts(
+        "\nWARNING: the show-doc command is deprecated. It will be removed " \
+        "from future Pry versions.\nPlease use 'show-source' with the -d " \
+        "(or --doc) switch instead\nExample: show-source #{obj_name} -d"
+      )
+    end
+
     # The docs for code_object prepared for display.
     def content_for(code_object)
       Code.new(render_doc_markup_for(code_object),
diff --git a/lib/pry/commands/show_source.rb b/lib/pry/commands/show_source.rb
index ea53e12a..0076f492 100644
--- a/lib/pry/commands/show_source.rb
+++ b/lib/pry/commands/show_source.rb
@@ -2,6 +2,8 @@ require 'pry/commands/show_info'
 
 class Pry
   class Command::ShowSource < Command::ShowInfo
+    include Pry::Helpers::DocumentationHelpers
+
     match 'show-source'
     group 'Introspection'
     description 'Show the source for a method or class.'
@@ -20,12 +22,14 @@ class Pry
       show-source Pry -a      # for all Pry class definitions (all monkey patches)
       show-source Pry.foo -e  # for class of the return value of expression `Pry.foo`
       show-source Pry --super # for superclass of Pry (Object class)
+      show-source Pry -d      # include documentation
 
       https://github.com/pry/pry/wiki/Source-browsing#wiki-Show_method
     BANNER
 
     def options(opt)
       opt.on :e, :eval, "evaluate the command's argument as a ruby expression and show the class its return value"
+      opt.on :d, :doc, 'include documentation in the output'
       super(opt)
     end
 
@@ -34,16 +38,74 @@ class Pry
         obj = target.eval(args.first)
         self.args = Array.new(1) { Module === obj ? obj.name : obj.class.name }
       end
+
       super
     end
 
     # The source for code_object prepared for display.
     def content_for(code_object)
+      content = ''
+      if opts.present?(:d)
+        code = Code.new(
+          render_doc_markup_for(code_object), start_line_for(code_object), :text
+        )
+        content += code.with_line_numbers(use_line_numbers?).to_s
+        content += "\n"
+      end
+
       code = Code.new(
-        code_object.source || [],
-        start_line_for(code_object)
+        code_object.source || [], start_line_for(code_object)
       )
-      code.with_line_numbers(use_line_numbers?).highlighted
+      content += code.with_line_numbers(use_line_numbers?).highlighted
+      content
+    end
+
+    # process the markup (if necessary) and apply colors
+    def render_doc_markup_for(code_object)
+      docs = docs_for(code_object)
+
+      if code_object.command?
+        # command '--help' shouldn't use markup highlighting
+        docs
+      else
+        if docs.empty?
+          raise CommandError, "No docs found for: #{
+            obj_name ? obj_name : 'current context'
+          }"
+        end
+        process_comment_markup(docs)
+      end
+    end
+
+    # Return docs for the code_object, adjusting for whether the code_object
+    # has yard docs available, in which case it returns those.
+    # (note we only have to check yard docs for modules since they can
+    # have multiple docs, but methods can only be doc'd once so we
+    # dont need to check them)
+    def docs_for(code_object)
+      if code_object.module_with_yard_docs?
+        # yard docs
+        code_object.yard_doc
+      else
+        # normal docs (i.e comments above method/module/command)
+        code_object.doc
+      end
+    end
+
+    # Which sections to include in the 'header', can toggle: :owner,
+    # :signature and visibility.
+    def header_options
+      super.merge signature: true
+    end
+
+    # figure out start line of docs by back-calculating based on
+    # number of lines in the comment and the start line of the code_object
+    # @return [Fixnum] start line of docs
+    def start_line_for(code_object)
+      return 1 if code_object.command? || opts.present?(:'base-one')
+      return 1 unless code_object.source_line
+
+      code_object.source_line - code_object.doc.lines.count
     end
   end
 
diff --git a/spec/commands/show_doc_spec.rb b/spec/commands/show_doc_spec.rb
index 2266f06a..a7c50902 100644
--- a/spec/commands/show_doc_spec.rb
+++ b/spec/commands/show_doc_spec.rb
@@ -18,6 +18,11 @@ describe "show-doc" do
     end
   end
 
+  it "emits a deprecation warning" do
+    expect(pry_eval(binding, 'show-doc @o.sample_method'))
+      .to match(/WARNING: the show-doc command is deprecated/)
+  end
+
   it 'should work even if #call is defined on Symbol' do
     class Symbol ; def call ; 5 ; end ; end
     expect(pry_eval(binding, "show-doc @o.sample_method")).to match(/sample doc/)
diff --git a/spec/commands/show_source_spec.rb b/spec/commands/show_source_spec.rb
index 8de5538b..00891efc 100644
--- a/spec/commands/show_source_spec.rb
+++ b/spec/commands/show_source_spec.rb
@@ -881,4 +881,23 @@ describe "show-source" do
       end
     end
   end
+
+  context "when the --doc switch is provided" do
+    before do
+      # Foo has docs.
+      class Foo
+        def bar
+          :bar
+        end
+      end
+    end
+
+    after { Object.remove_const(:Foo) }
+
+    it "shows documentation for the code object along with source code" do
+      expect(pry_eval(binding, "show-source Foo -d")).to match(
+        /Foo has docs\.\n\s+class Foo/
+      )
+    end
+  end
 end