[ruby/irb] Print deprecation warning for help command

(ruby/irb#567)

* Give show_doc its own command class

* Print deprecation warning for `help` command

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

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

lib/irb/extend-command.rb

@@ -157,10 +157,14 @@ def irb_context
 
       [
         :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"
       ],

test/irb/test_cmd.rb

@@ -783,19 +783,33 @@ def test_ls_with_no_singleton_class
   end
 
   class ShowDocTest < CommandTestCase
-    def test_help_and_show_doc
-      ["help", "show_doc"].each do |cmd|
-        out, err = execute_lines(
-          "#{cmd} String#gsub\n",
-          "\n",
-        )
+    def test_help
+      out, err = execute_lines(
+        "help String#gsub\n",
+        "\n",
+      )
 
-        # the former is what we'd get without document content installed, like on CI
-        # the latter is what we may get locally
-        possible_rdoc_output = [/Nothing known about String#gsub/, /gsub\(pattern\)/]
-        assert_empty err
-        assert(possible_rdoc_output.any? { |output| output.match?(out) }, "Expect the `#{cmd}` command to match one of the possible outputs. Got:\n#{out}")
-      end
+      # the former is what we'd get without document content installed, like on CI
+      # the latter is what we may get locally
+      possible_rdoc_output = [/Nothing known about String#gsub/, /gsub\(pattern\)/]
+      assert_include err, "[Deprecation] The `help` command will be repurposed to display command help in the future.\n"
+      assert(possible_rdoc_output.any? { |output| output.match?(out) }, "Expect the `help` command to match one of the possible outputs. Got:\n#{out}")
+    ensure
+      # this is the only way to reset the redefined method without coupling the test with its implementation
+      EnvUtil.suppress_warning { load "irb/cmd/help.rb" }
+    end
+
+    def test_show_doc
+      out, err = execute_lines(
+        "show_doc String#gsub\n",
+        "\n",
+      )
+
+      # the former is what we'd get without document content installed, like on CI
+      # the latter is what we may get locally
+      possible_rdoc_output = [/Nothing known about String#gsub/, /gsub\(pattern\)/]
+      assert_not_include err, "[Deprecation]"
+      assert(possible_rdoc_output.any? { |output| output.match?(out) }, "Expect the `show_doc` command to match one of the possible outputs. Got:\n#{out}")
     ensure
       # this is the only way to reset the redefined method without coupling the test with its implementation
       EnvUtil.suppress_warning { load "irb/cmd/help.rb" }