3 files changed, 65 insertions, 45 deletions
diff --git a/lib/irb/cmd/help.rb b/lib/irb/cmd/help.rb
index 539d20a119..64b885c383 100644
--- a/lib/irb/cmd/help.rb
+++ b/lib/irb/cmd/help.rb
@@ -1,55 +1,23 @@
-# frozen_string_literal: false
-#
-#   help.rb - helper using ri
-#
+# frozen_string_literal: true
 
-require_relative "nop"
+require_relative "show_doc"
 
 module IRB
-  # :stopdoc:
-
   module ExtendCommand
-    class Help < Nop
-      class << self
-        def transform_args(args)
-          # Return a string literal as is for backward compatibility
-          if args.empty? || string_literal?(args)
-            args
-          else # Otherwise, consider the input as a String for convenience
-            args.strip.dump
-          end
-        end
-      end
-
+    class Help < ShowDoc
       category "Context"
-      description "Enter the mode to look up RI documents."
-
-      def execute(*names)
-        require 'rdoc/ri/driver'
-
-        unless self.class.const_defined?(:Ri)
-          opts = RDoc::RI::Driver.process_args([])
-          self.class.const_set(:Ri, RDoc::RI::Driver.new(opts))
-        end
+      description "[DEPRECATED] Enter the mode to look up RI documents."
 
-        if names.empty?
-          Ri.interactive
-        else
-          names.each do |name|
-            begin
-              Ri.display_name(name.to_s)
-            rescue RDoc::RI::Error
-              puts $!.message
-            end
-          end
-        end
+      DEPRECATION_MESSAGE = <<~MSG
+        [Deprecation] The `help` command will be repurposed to display command help in the future.
+        For RI document lookup, please use the `show_doc` command instead.
+        For command help, please use `show_cmds` for now.
+      MSG
 
-        nil
-      rescue LoadError, SystemExit
-        warn "Can't display document because `rdoc` is not installed."
+      def execute(*names)
+        warn DEPRECATION_MESSAGE
+        super
       end
     end
   end
-
-  # :startdoc:
 end
diff --git a/lib/irb/cmd/show_doc.rb b/lib/irb/cmd/show_doc.rb
new file mode 100644
index 0000000000..99dd9ab95a
--- /dev/null
+++ b/lib/irb/cmd/show_doc.rb
@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "nop"
+
+module IRB
+  module ExtendCommand
+    class ShowDoc < Nop
+      class << self
+        def transform_args(args)
+          # Return a string literal as is for backward compatibility
+          if args.empty? || string_literal?(args)
+            args
+          else # Otherwise, consider the input as a String for convenience
+            args.strip.dump
+          end
+        end
+      end
+
+      category "Context"
+      description "Enter the mode to look up RI documents."
+
+      def execute(*names)
+        require 'rdoc/ri/driver'
+
+        unless ShowDoc.const_defined?(:Ri)
+          opts = RDoc::RI::Driver.process_args([])
+          ShowDoc.const_set(:Ri, RDoc::RI::Driver.new(opts))
+        end
+
+        if names.empty?
+          Ri.interactive
+        else
+          names.each do |name|
+            begin
+              Ri.display_name(name.to_s)
+            rescue RDoc::RI::Error
+              puts $!.message
+            end
+          end
+        end
+
+        nil
+      rescue LoadError, SystemExit
+        warn "Can't display document because `rdoc` is not installed."
+      end
+    end
+  end
+end
diff --git a/lib/irb/extend-command.rb b/lib/irb/extend-command.rb
index 1a252bb42a..e377148fb4 100644
--- a/lib/irb/extend-command.rb
+++ b/lib/irb/extend-command.rb
@@ -157,11 +157,15 @@ module IRB # :nodoc:
 
       [
         :irb_help, :Help, "cmd/help",
-        [:show_doc, NO_OVERRIDE],
         [:help, NO_OVERRIDE],
       ],
 
       [
+        :irb_show_doc, :ShowDoc, "cmd/show_doc",
+        [:show_doc, NO_OVERRIDE],
+      ],
+
+      [
         :irb_info, :IrbInfo, "cmd/irb_info"
       ],