Display command description in doc dialog on tab completion

Author: st0012

lib/irb/command/base.rb

@@ -37,11 +37,49 @@ def execute(irb_context, arg)
           puts e.message
         end
 
+        # Returns formatted lines for display in the doc dialog popup.
+        def doc_dialog_content(name, width)
+          lines = []
+          lines << Color.colorize(name, [:BOLD, :BLUE]) + Color.colorize(" (command)", [:CYAN])
+          lines << ""
+          lines.concat(wrap_lines(description, width))
+          if help_message
+            lines << ""
+            lines.concat(wrap_lines(help_message, width))
+          end
+          lines
+        end
+
         private
 
         def highlight(text)
           Color.colorize(text, [:BOLD, :BLUE])
         end
+
+        def wrap_lines(text, width)
+          text.lines.flat_map do |line|
+            line = line.chomp
+            next [''] if line.empty?
+            next [line] if line.length <= width
+
+            indent = line[/\A\s*/]
+            words = line.strip.split(/\s+/)
+            result = []
+            current = indent.dup
+            words.each do |word|
+              if current == indent
+                current << word
+              elsif current.length + 1 + word.length <= width
+                current << ' ' << word
+              else
+                result << current
+                current = indent.dup + word
+              end
+            end
+            result << current unless current == indent
+            result
+          end
+        end
       end
 
       def initialize(irb_context)

lib/irb/completion.rb

@@ -8,6 +8,29 @@
 require_relative 'ruby-lex'
 
 module IRB
+  class DocumentTarget # :nodoc:
+    attr_reader :name
+
+    def initialize(name)
+      @name = name
+    end
+  end
+
+  class CommandDocument < DocumentTarget # :nodoc:
+  end
+
+  # Represents a method/class documentation target. May hold multiple names
+  # when the receiver is ambiguous (e.g. `{}.any?` could be Hash#any? or Proc#any?).
+  # The dialog popup uses only the first name; the full-screen display renders all.
+  class MethodDocument < DocumentTarget # :nodoc:
+    attr_reader :names
+
+    def initialize(*names)
+      super(names.first)
+      @names = names
+    end
+  end
+
   class BaseCompletor # :nodoc:
 
     # Set of reserved words used by Ruby, you should not use these for
@@ -76,6 +99,12 @@ def command_candidates(target)
       end
     end
 
+    def command_document_target(preposing, matched)
+      if preposing.empty? && IRB::Command.command_names.include?(matched)
+        CommandDocument.new(matched)
+      end
+    end
+
     def retrieve_files_to_require_relative_from_current_dir
       @files_from_current_dir ||= Dir.glob("**/*.{rb,#{RbConfig::CONFIG['DLEXT']}}", base: '.').map { |path|
         path.sub(/\.(rb|#{RbConfig::CONFIG['DLEXT']})\z/, '')
@@ -118,8 +147,10 @@ def completion_candidates(preposing, target, _postposing, bind:)
     end
 
     def doc_namespace(preposing, matched, _postposing, bind:)
-      result = ReplTypeCompletor.analyze(preposing + matched, binding: bind, filename: @context.irb_path)
-      result&.doc_namespace('')
+      command_document_target(preposing, matched) || begin
+        result = ReplTypeCompletor.analyze(preposing + matched, binding: bind, filename: @context.irb_path)
+        result&.doc_namespace('')
+      end
     end
   end
 
@@ -201,8 +232,8 @@ def completion_candidates(preposing, target, postposing, bind:)
       commands | completion_data
     end
 
-    def doc_namespace(_preposing, matched, _postposing, bind:)
-      retrieve_completion_data(matched, bind: bind, doc_namespace: true)
+    def doc_namespace(preposing, matched, _postposing, bind:)
+      command_document_target(preposing, matched) || retrieve_completion_data(matched, bind: bind, doc_namespace: true)
     end
 
     def retrieve_completion_data(input, bind:, doc_namespace:)

lib/irb/input-method.rb

@@ -315,9 +315,17 @@ def auto_indent(&block)
       @auto_indent_proc = block
     end
 
-    def retrieve_doc_namespace(matched)
+    def retrieve_document_target(matched)
       preposing, _target, postposing, bind = @completion_params
-      @completor.doc_namespace(preposing, matched, postposing, bind: bind)
+      result = @completor.doc_namespace(preposing, matched, postposing, bind: bind)
+      case result
+      when DocumentTarget, nil
+        result
+      when Array
+        MethodDocument.new(*result)
+      when String
+        MethodDocument.new(result)
+      end
     end
 
     def rdoc_ri_driver
@@ -345,22 +353,25 @@ def show_doc_dialog_proc
         cursor_pos_to_render, result, pointer, autocomplete_dialog = context.pop(4)
         return nil if result.nil? || pointer.nil? || pointer < 0
 
-        name = input_method.retrieve_doc_namespace(result[pointer])
-        # Use first one because document dialog does not support multiple namespaces.
-        name = name.first if name.is_a?(Array)
-
-        show_easter_egg = name&.match?(/\ARubyVM/) && !ENV['RUBY_YES_I_AM_NOT_A_NORMAL_USER']
+        matched_text = result[pointer]
+        show_easter_egg = matched_text&.match?(/\ARubyVM/) && !ENV['RUBY_YES_I_AM_NOT_A_NORMAL_USER']
+        target = show_easter_egg ? nil : input_method.retrieve_document_target(matched_text)
 
         x, width = input_method.dialog_doc_position(cursor_pos_to_render, autocomplete_dialog, screen_width)
         return nil unless x
 
         dialog.trap_key = ALT_D_SEQUENCES
         open_doc = key.match?(dialog.name)
 
-        contents = if show_easter_egg
-          input_method.easter_egg_dialog_contents(open_doc: open_doc)
+        contents = case target
+        when CommandDocument
+          input_method.command_doc_dialog_contents(target.name, width, open_doc: open_doc)
+        when MethodDocument
+          input_method.rdoc_dialog_contents(target.name, width, open_doc: open_doc)
         else
-          input_method.rdoc_dialog_contents(name, width, open_doc: open_doc)
+          if show_easter_egg
+            input_method.easter_egg_dialog_contents(open_doc: open_doc)
+          end
         end
         return nil unless contents
 
@@ -370,6 +381,23 @@ def show_doc_dialog_proc
       }
     end
 
+    def command_doc_dialog_contents(command_name, width, open_doc: false)
+      command_class = IRB::Command.load_command(command_name)
+      return unless command_class
+
+      if open_doc
+        content = command_class.help_message || command_class.description
+        begin
+          print "\e[?1049h"
+          Pager.page_content(content)
+        ensure
+          print "\e[?1049l"
+        end
+      end
+
+      [PRESS_ALT_D_TO_READ_FULL_DOC, ""] + command_class.doc_dialog_content(command_name, width)
+    end
+
     def easter_egg_dialog_contents(open_doc: false)
       IRB.__send__(:easter_egg) if open_doc
       type = STDOUT.external_encoding == Encoding::UTF_8 ? :unicode : :ascii
@@ -447,31 +475,40 @@ def dialog_doc_position(cursor_pos_to_render, autocomplete_dialog, screen_width)
     end
 
     def display_document(matched)
-      driver = rdoc_ri_driver
-      return unless driver
-
-      if matched =~ /\A(?:::)?RubyVM/ && !ENV['RUBY_YES_I_AM_NOT_A_NORMAL_USER']
-        IRB.__send__(:easter_egg)
-        return
-      end
+      target = retrieve_document_target(matched)
+      return unless target
+
+      case target
+      when CommandDocument
+        command_class = IRB::Command.load_command(target.name)
+        if command_class
+          content = command_class.help_message || command_class.description
+          Pager.page_content(content)
+        end
+      when MethodDocument
+        driver = rdoc_ri_driver
+        return unless driver
 
-      namespace = retrieve_doc_namespace(matched)
-      return unless namespace
+        if matched =~ /\A(?:::)?RubyVM/ && !ENV['RUBY_YES_I_AM_NOT_A_NORMAL_USER']
+          IRB.__send__(:easter_egg)
+          return
+        end
 
-      if namespace.is_a?(Array)
-        out = RDoc::Markup::Document.new
-        namespace.each do |m|
+        if target.names.length > 1
+          out = RDoc::Markup::Document.new
+          target.names.each do |m|
+            begin
+              driver.add_method(out, m)
+            rescue RDoc::RI::Driver::NotFoundError
+            end
+          end
+          driver.display(out)
+        else
           begin
-            driver.add_method(out, m)
+            driver.display_names([target.name])
           rescue RDoc::RI::Driver::NotFoundError
           end
         end
-        driver.display(out)
-      else
-        begin
-          driver.display_names([namespace])
-        rescue RDoc::RI::Driver::NotFoundError
-        end
       end
     end
 

test/irb/test_completion.rb

@@ -25,6 +25,22 @@ def test_command_completion
         assert_include(completor.completion_candidates('', 'show_s', '', bind: binding), 'show_source')
         assert_not_include(completor.completion_candidates(';', 'show_s', '', bind: binding), 'show_source')
       end
+
+      def test_command_document_target
+        completor = IRB::RegexpCompletor.new
+        # Command with empty preposing should return a CommandDocument
+        result = completor.doc_namespace('', 'help', '', bind: binding)
+        assert_instance_of(IRB::CommandDocument, result)
+        assert_equal('help', result.name)
+
+        result = completor.doc_namespace('', 'show_source', '', bind: binding)
+        assert_instance_of(IRB::CommandDocument, result)
+        assert_equal('show_source', result.name)
+
+        # Command with non-empty preposing should not return a CommandDocument
+        result = completor.doc_namespace(';', 'help', '', bind: binding)
+        refute_instance_of(IRB::CommandDocument, result)
+      end
     end
 
     class MethodCompletionTest < CompletionTest

test/irb/test_input_method.rb

@@ -186,10 +186,63 @@ def test_perfect_matching_handles_nil_namespace
       assert_empty(out)
     end
 
+    def test_command_doc_display_with_help_message
+      out, _err = capture_output do
+        display_document("show_source", binding)
+      end
+
+      # When help_message is available, it is displayed
+      assert_include(out, "Usage: show_source")
+    end
+
+    def test_command_doc_display_without_help_message
+      out, _err = capture_output do
+        display_document("history", binding)
+      end
+
+      # When no help_message, description is displayed
+      assert_include(out, IRB::Command::History.description)
+    end
+
     private
 
     def has_rdoc_content?
       File.exist?(RDoc::RI::Paths::BASE)
     end
   end if defined?(RDoc)
+
+  class CommandDocDialogContentTest < TestCase
+    def setup
+      @conf_backup = IRB.conf.dup
+      IRB.init_config(nil)
+    end
+
+    def teardown
+      IRB.conf.replace(@conf_backup)
+    end
+
+    def test_doc_dialog_content_with_description_only
+      lines = IRB::Command::History.doc_dialog_content("history", 40)
+      assert lines[0].include?("(command)")
+      # Description words should all be present (may be wrapped across lines)
+      content = lines.join(" ")
+      IRB::Command::History.description.split.each do |word|
+        assert_include content, word
+      end
+    end
+
+    def test_doc_dialog_content_with_help_message
+      lines = IRB::Command::ShowSource.doc_dialog_content("show_source", 60)
+      assert lines[0].include?("(command)")
+      assert_include lines.join("\n"), "Usage: show_source"
+    end
+
+    def test_doc_dialog_content_wraps_long_lines
+      lines = IRB::Command::Help.doc_dialog_content("help", 30)
+      lines.each do |line|
+        stripped = line.gsub(/\e\[[0-9;]*m/, '') # strip ANSI codes
+        assert_operator stripped.length, :<=, 30, "Line exceeds width: #{line.inspect}"
+      end
+    end
+  end
 end

test/irb/test_type_completor.rb

@@ -81,6 +81,21 @@ def test_command_completion
       assert_not_include(@completor.completion_candidates(';', 'show_s', '', bind: binding), 'show_source')
     end
 
+    def test_command_document_target
+      # Command with empty preposing should return a CommandDocument
+      result = @completor.doc_namespace('', 'help', '', bind: binding)
+      assert_instance_of(IRB::CommandDocument, result)
+      assert_equal('help', result.name)
+
+      result = @completor.doc_namespace('', 'show_source', '', bind: binding)
+      assert_instance_of(IRB::CommandDocument, result)
+      assert_equal('show_source', result.name)
+
+      # Command with non-empty preposing should not return a CommandDocument
+      result = @completor.doc_namespace(';', 'help', '', bind: binding)
+      refute_instance_of(IRB::CommandDocument, result)
+    end
+
     def test_type_completor_handles_encoding_errors_gracefully
       invalid_method_name = "b\xff".dup.force_encoding(Encoding::ASCII_8BIT)