rdoc 7.2.0 → 8.0.0

data/lib/rdoc/stats.rb

@@ -7,6 +7,19 @@ class RDoc::Stats
 
   include RDoc::Text
 
+  ##
+  # Display order for item types in the coverage report
+
+  TYPE_ORDER = %w[Class Module Constant Attribute Method].freeze
+
+  ##
+  # Message displayed when all items are documented
+
+  GREAT_JOB_MESSAGE = <<~MSG
+    100% documentation!
+    Great Job!
+  MSG
+
   ##
   # Output level for the coverage report
 
@@ -39,10 +52,17 @@ class RDoc::Stats
     @start            = Time.now
     @undoc_params     = 0
 
+    self.verbosity = verbosity
+  end
+
+  ##
+  # Sets the verbosity level, rebuilding the display outputter.
+
+  def verbosity=(verbosity)
     @display = case verbosity
-               when 0 then Quiet.new   num_files
-               when 1 then Normal.new  num_files
-               else        Verbose.new num_files
+               when 0 then Quiet.new   @num_files
+               when 1 then Normal.new  @num_files
+               else        Verbose.new @num_files
                end
   end
 
@@ -186,18 +206,6 @@ class RDoc::Stats
     @fully_documented
   end
 
-  ##
-  # A report that says you did a great job!
-
-  def great_job
-    report = RDoc::Markup::Document.new
-
-    report << RDoc::Markup::Paragraph.new('100% documentation!')
-    report << RDoc::Markup::Paragraph.new('Great Job!')
-
-    report
-  end
-
   ##
   # Calculates the percentage of items documented.
 
@@ -223,48 +231,55 @@ class RDoc::Stats
     if @coverage_level.zero? then
       calculate
 
-      return great_job if @num_items == @doc_items
+      return GREAT_JOB_MESSAGE if @num_items == @doc_items
     end
 
-    ucm = @store.unique_classes_and_modules
+    items, empty_classes = collect_undocumented_items
 
-    report = RDoc::Markup::Document.new
-    report << RDoc::Markup::Paragraph.new('The following items are not documented:')
-    report << RDoc::Markup::BlankLine.new
-
-    ucm.sort.each do |cm|
-      body = report_class_module(cm) {
-        [
-          report_constants(cm),
-          report_attributes(cm),
-          report_methods(cm),
-        ].compact
-      }
+    if @coverage_level > 0 then
+      calculate
 
-      report << body if body
+      return GREAT_JOB_MESSAGE if @num_items == @doc_items
     end
 
-    if @coverage_level > 0 then
-      calculate
+    report = +""
+    report << "The following items are not documented:\n\n"
 
-      return great_job if @num_items == @doc_items
+    # Referenced-but-empty classes
+    empty_classes.each do |cm|
+      report << "#{cm.full_name} is referenced but empty.\n"
+      report << "It probably came from another project.  I'm sorry I'm holding it against you.\n\n"
     end
 
-    report
-  end
+    # Group items by file, then by type
+    by_file = items.group_by { |item| item[:file] }
 
-  ##
-  # Returns a report on undocumented attributes in ClassModule +cm+
+    by_file.sort_by { |file, _| file }.each do |file, file_items|
+      report << "#{file}:\n"
 
-  def report_attributes(cm)
-    return if cm.attributes.empty?
+      by_type = file_items.group_by { |item| item[:type] }
 
-    report = []
+      TYPE_ORDER.each do |type|
+        next unless by_type[type]
+
+        report << "  #{type}:\n"
+
+        sorted = by_type[type].sort_by { |item| [item[:line] || 0, item[:name]] }
+        name_width = sorted.reduce(0) { |max, item| item[:line] && item[:name].length > max ? item[:name].length : max }
+
+        sorted.each do |item|
+          if item[:line]
+            report << "    %-*s %s:%d\n" % [name_width, item[:name], item[:file], item[:line]]
+          else
+            report << "    #{item[:name]}\n"
+          end
+
+          if item[:undoc_params]
+            report << "      Undocumented params: #{item[:undoc_params].join(', ')}\n"
+          end
+        end
+      end
 
-    cm.attributes.each do |attr|
-      next if attr.documented?
-      line = attr.line ? ":#{attr.line}" : nil
-      report << "  #{attr.definition} :#{attr.name} # in file #{attr.file.full_name}#{line}\n"
       report << "\n"
     end
 
@@ -272,115 +287,128 @@ class RDoc::Stats
   end
 
   ##
-  # Returns a report on undocumented items in ClassModule +cm+
-
-  def report_class_module(cm)
-    return if cm.fully_documented? and @coverage_level.zero?
-    return unless cm.display?
-
-    report = RDoc::Markup::Document.new
+  # Collects all undocumented items across all classes and modules.
+  # Returns [items, empty_classes] where items is an Array of Hashes
+  # with keys :type, :name, :file, :line, and empty_classes is an
+  # Array of ClassModule objects that are referenced but have no files.
 
-    if cm.in_files.empty? then
-      report << RDoc::Markup::Paragraph.new("#{cm.definition} is referenced but empty.")
-      report << RDoc::Markup::Paragraph.new("It probably came from another project.  I'm sorry I'm holding it against you.")
+  def collect_undocumented_items
+    empty_classes = []
+    items = []
 
-      return report
-    elsif cm.documented? then
-      documented = true
-      klass = RDoc::Markup::Verbatim.new("#{cm.definition} # is documented\n")
-    else
-      report << RDoc::Markup::Paragraph.new('In files:')
+    @store.unique_classes_and_modules.each do |class_module|
+      next unless class_module.display?
 
-      list = RDoc::Markup::List.new :BULLET
-
-      cm.in_files.each do |file|
-        para = RDoc::Markup::Paragraph.new file.full_name
-        list << RDoc::Markup::ListItem.new(nil, para)
+      if class_module.in_files.empty?
+        empty_classes << class_module
+        next
       end
 
-      report << list
-      report << RDoc::Markup::BlankLine.new
+      unless class_module.documented? || class_module.full_name == 'Object'
+        collect_undocumented_class_module(class_module, items)
+      end
 
-      klass = RDoc::Markup::Verbatim.new("#{cm.definition}\n")
+      collect_undocumented_constants(class_module, items)
+      collect_undocumented_attributes(class_module, items)
+      collect_undocumented_methods(class_module, items)
     end
 
-    klass << "\n"
-
-    body = yield.flatten # HACK remove #flatten
-
-    if body.empty? then
-      return if documented
+    [items, empty_classes]
+  end
 
-      klass.parts.pop
-    else
-      klass.parts.concat body
+  ##
+  # Collects undocumented classes or modules from +class_module+ into +items+.
+  # Reopened classes/modules are reported in every file they appear in.
+
+  def collect_undocumented_class_module(class_module, items)
+    class_module.in_files.map(&:full_name).uniq.each do |file|
+      items << {
+        type: class_module.type.capitalize,
+        name: class_module.full_name,
+        file: file,
+        line: nil,
+      }
     end
+  end
+
+  ##
+  # Collects undocumented constants from +class_module+ into +items+.
 
-    klass << "end\n"
+  def collect_undocumented_constants(class_module, items)
+    class_module.constants.each do |constant|
+      next unless constant.display?
+      next if constant.documented? || constant.is_alias_for
 
-    report << klass
+      file = constant.file&.full_name
+      next unless file
 
-    report
+      items << {
+        type: "Constant",
+        name: constant.full_name,
+        file: file,
+        line: constant.line,
+      }
+    end
   end
 
   ##
-  # Returns a report on undocumented constants in ClassModule +cm+
+  # Collects undocumented attributes from +class_module+ into +items+.
 
-  def report_constants(cm)
-    return if cm.constants.empty?
-
-    report = []
+  def collect_undocumented_attributes(class_module, items)
+    class_module.attributes.each do |attr|
+      next unless attr.display?
+      next if attr.documented?
 
-    cm.constants.each do |constant|
-      # TODO constant aliases are listed in the summary but not reported
-      # figure out what to do here
-      next if constant.documented? || constant.is_alias_for
+      file = attr.file&.full_name
+      next unless file
 
-      line = constant.line ? ":#{constant.line}" : line
-      report << "  # in file #{constant.file.full_name}#{line}\n"
-      report << "  #{constant.name} = nil\n"
-      report << "\n"
+      scope = attr.singleton ? "." : "#"
+      items << {
+        type: "Attribute",
+        name: "#{class_module.full_name}#{scope}#{attr.name}",
+        file: file,
+        line: attr.line,
+      }
     end
-
-    report
   end
 
   ##
-  # Returns a report on undocumented methods in ClassModule +cm+
+  # Collects undocumented methods from +class_module+ into +items+.
+  # At coverage level > 0, also counts undocumented parameters.
 
-  def report_methods(cm)
-    return if cm.method_list.empty?
+  def collect_undocumented_methods(class_module, items)
+    class_module.each_method do |method|
+      next unless method.display?
+      next if method.documented? && @coverage_level.zero?
 
-    report = []
+      undoc_param_names = nil
 
-    cm.each_method do |method|
-      next if method.documented? and @coverage_level.zero?
-
-      if @coverage_level > 0 then
+      if @coverage_level > 0
         params, undoc = undoc_params method
-
         @num_params += params
 
-        unless undoc.empty? then
+        unless undoc.empty?
           @undoc_params += undoc.length
-
-          undoc = undoc.map do |param| "+#{param}+" end
-          param_report = "  # #{undoc.join ', '} is not documented\n"
+          undoc_param_names = undoc
         end
       end
 
-      next if method.documented? and not param_report
+      next if method.documented? && !undoc_param_names
 
-      line = method.line ? ":#{method.line}" : nil
-      scope = method.singleton ? 'self.' : nil
+      file = method.file&.full_name
+      next unless file
 
-      report << "  # in file #{method.file.full_name}#{line}\n"
-      report << param_report if param_report
-      report << "  def #{scope}#{method.name}#{method.params}; end\n"
-      report << "\n"
-    end
+      scope = method.singleton ? "." : "#"
+      item = {
+        type: "Method",
+        name: "#{class_module.full_name}#{scope}#{method.name}",
+        file: file,
+        line: method.line,
+      }
+      item[:undoc_params] = undoc_param_names if undoc_param_names
 
-    report
+      items << item
+    end
   end
 
   ##
@@ -400,12 +428,10 @@ class RDoc::Stats
       @undoc_params,
     ].max.to_s.length
 
-    report = RDoc::Markup::Verbatim.new
+    report = +""
 
     report << "Files:      %*d\n" % [num_width, @num_files]
-
     report << "\n"
-
     report << "Classes:    %*d (%*d undocumented)\n" % [
       num_width, @num_classes, undoc_width, @undoc_classes]
     report << "Modules:    %*d (%*d undocumented)\n" % [
@@ -419,17 +445,14 @@ class RDoc::Stats
     report << "Parameters: %*d (%*d undocumented)\n" % [
       num_width, @num_params, undoc_width, @undoc_params] if
         @coverage_level > 0
-
     report << "\n"
-
     report << "Total:      %*d (%*d undocumented)\n" % [
       num_width, @num_items, undoc_width, @undoc_items]
-
     report << "%6.2f%% documented\n" % percent_doc
     report << "\n"
     report << "Elapsed: %0.1fs\n" % (Time.now - @start)
 
-    RDoc::Markup::Document.new report
+    report
   end
 
   ##

data/lib/rdoc/store.rb

@@ -193,6 +193,121 @@ class RDoc::Store
     top_level
   end
 
+  ##
+  # Removes a file and its classes/modules from the store.  Used by the
+  # live-reloading server when a source file is deleted.
+  #
+  # Note: this does not handle reopened classes correctly.  If a class is
+  # defined across multiple files (e.g. +Foo+ in both +a.rb+ and +b.rb+),
+  # deleting one file removes the entire class from the store — including
+  # the parts contributed by the other file.  Saving the remaining file
+  # triggers a re-parse that restores it.
+
+  def remove_file(relative_name)
+    top_level = @files_hash.delete(relative_name)
+    @text_files_hash.delete(relative_name)
+    @c_class_variables.delete(relative_name)
+    @c_singleton_class_variables.delete(relative_name)
+    return unless top_level
+
+    remove_classes_and_modules(top_level.classes_or_modules)
+  end
+
+  ##
+  # Removes a file's contributions (methods, constants, comments, etc.)
+  # from its classes and modules.  If no other files contribute to a
+  # class or module, it is removed from the store entirely.  This
+  # prevents duplication when the file is re-parsed while preserving
+  # shared namespaces like +RDoc+ that span many files.
+
+  def clear_file_contributions(relative_name, keep_position: false)
+    top_level = @files_hash[relative_name]
+    return unless top_level
+
+    top_level.classes_or_modules.each do |cm|
+      # Remove methods and attributes contributed by this file
+      cm.method_list.reject! { |m| m.file == top_level }
+      cm.attributes.reject! { |a| a.file == top_level }
+
+      # Rebuild methods_hash from remaining methods and attributes
+      cm.methods_hash.clear
+      cm.method_list.each { |m| cm.methods_hash[m.pretty_name] = m }
+      cm.attributes.each { |a| cm.methods_hash[a.pretty_name] = a }
+
+      # Remove constants contributed by this file
+      cm.constants.reject! { |c| c.file == top_level }
+      cm.constants_hash.clear
+      cm.constants.each { |c| cm.constants_hash[c.name] = c }
+
+      # Remove includes, extends, and aliases from this file
+      cm.includes.reject! { |i| i.file == top_level }
+      cm.extends.reject! { |e| e.file == top_level }
+      cm.aliases.reject! { |a| a.file == top_level }
+      cm.external_aliases.reject! { |a| a.file == top_level }
+
+      # Clear or remove comment entries from this file
+      if cm.is_a?(RDoc::ClassModule)
+        if keep_position
+          cm.comment_location[top_level] = [] if cm.comment_location.key?(top_level)
+        else
+          cm.comment_location.delete(top_level)
+        end
+        cm.rebuild_comment_from_location
+      end
+
+      unless keep_position
+        # Remove this file from the class/module's file list
+        cm.in_files.delete(top_level)
+
+        # If no files contribute to this class/module anymore, remove it
+        # from the store entirely.  This handles file deletion correctly
+        # for classes that are only defined in the deleted file, while
+        # preserving classes that span multiple files.
+        if cm.in_files.empty?
+          if cm.is_a?(RDoc::NormalModule)
+            @modules_hash.delete(cm.full_name)
+          else
+            @classes_hash.delete(cm.full_name)
+          end
+          cm.parent&.classes_hash&.delete(cm.name)
+          cm.parent&.modules_hash&.delete(cm.name)
+        end
+      end
+    end
+
+    # Clear the TopLevel's class/module list to prevent duplicates
+    top_level.classes_or_modules.clear
+  end
+
+  ##
+  # Removes stale empty placeholders left by +clear_file_contributions+ with
+  # <tt>keep_position: true</tt>.  After re-parsing, a file may no longer
+  # define a class it previously contributed to, leaving an empty entry in
+  # +comment_location+ and a stale +in_files+ reference.  Call this after
+  # all re-parsing is complete.
+
+  def cleanup_stale_contributions
+    all_classes_and_modules.each do |cm|
+      cm.comment_location.delete_if { |_, comments| comments.empty? }
+      cm.rebuild_comment_from_location
+
+      cm.in_files.select! { |tl| cm.comment_location.key?(tl) ||
+        cm.method_list.any? { |m| m.file == tl } ||
+        cm.attributes.any? { |a| a.file == tl } ||
+        cm.constants.any? { |c| c.file == tl } }
+
+      if cm.in_files.empty?
+        if cm.is_a?(RDoc::NormalModule)
+          @modules_hash.delete(cm.full_name)
+        else
+          @classes_hash.delete(cm.full_name)
+        end
+        cm.parent&.classes_hash&.delete(cm.name)
+        cm.parent&.modules_hash&.delete(cm.name)
+      end
+    end
+  end
+
   ##
   # Make sure any references to C variable names are resolved to the corresponding class.
   #
@@ -206,11 +321,11 @@ class RDoc::Store
   end
 
   ##
-  # Sets the parser of +absolute_name+, unless it from a source code file.
+  # Caches +relative_name+ in the text files hash, if it is a text file.
 
-  def update_parser_of_file(absolute_name, parser)
-    if top_level = @files_hash[absolute_name] then
-      @text_files_hash[absolute_name] = top_level if top_level.text?
+  def cache_text_file(relative_name)
+    if top_level = @files_hash[relative_name]
+      @text_files_hash[relative_name] = top_level if top_level.text?
     end
   end
 
@@ -228,6 +343,86 @@ class RDoc::Store
     @classes_hash.values + @modules_hash.values
   end
 
+  ##
+  # Returns a hash mapping class/module names to their paths, for use
+  # by type signature linking. Maps both qualified names (Foo::Bar) and
+  # unambiguous unqualified names (Bar). Ambiguous unqualified names
+  # (where multiple classes share the same name) are excluded to avoid
+  # wrong links. Cached after first call.
+
+  ##
+  # Invalidates the cached type name lookup.  Server mode calls this after
+  # re-parsing changes the set of classes and modules.
+
+  def invalidate_type_name_lookup # :nodoc:
+    @type_name_lookup = nil
+  end
+
+  def type_name_lookup
+    @type_name_lookup ||= begin
+      lookup = {}
+      unqualified_names = {}
+      ambiguous_names = {}
+      all_classes_and_modules.each do |cm|
+        lookup[cm.full_name] = cm.path
+        unqualified_name = cm.name
+
+        if ambiguous_names[unqualified_name]
+          # already known ambiguous, skip
+        elsif unqualified_names.key?(unqualified_name)
+          unqualified_names.delete(unqualified_name)
+          ambiguous_names[unqualified_name] = true
+        else
+          unqualified_names[unqualified_name] = cm.path
+        end
+      end
+      lookup.merge!(unqualified_names)
+    end
+  end
+
+  ##
+  # Stores RBS type signatures loaded from sidecar .rbs files, keyed by
+  # "ClassName#method" or "ClassName.method".  Replaces any previously
+  # stored set, so passing +{}+ clears it.  Inline +#:+ annotations on
+  # method objects are NOT touched — those are owned by the source file.
+
+  def merge_rbs_signatures(signatures)
+    @rbs_signatures = signatures
+  end
+
+  ##
+  # Returns the RBS type signature lines for +method_attr+ from loaded
+  # sidecar +.rbs+ files, or +nil+ if none.  Falls through to the
+  # canonical method for aliases, and handles +initialize+ -> +.new+
+  # singleton mapping.
+
+  def rbs_signature_for(method_attr)
+    return nil unless @rbs_signatures
+    cm = method_attr.parent
+    return nil unless cm.respond_to?(:full_name)
+
+    key = method_attr.singleton ? "#{cm.full_name}.#{method_attr.name}" : "#{cm.full_name}##{method_attr.name}"
+    sig = @rbs_signatures[key]
+
+    # RBS keys constructors as #initialize, but RDoc renames them to .new
+    if !sig && method_attr.name == 'new' && method_attr.singleton
+      sig = @rbs_signatures["#{cm.full_name}#initialize"]
+    end
+
+    # For aliases, fall through to the canonical method (its inline #:
+    # takes precedence over any sidecar signature on the alias's name).
+    if !sig && method_attr.is_alias_for
+      canonical = method_attr.is_alias_for
+      sig = canonical.type_signature_lines || rbs_signature_for(canonical)
+    end
+
+    sig
+  end
+
+  def clear_rbs_signatures # :nodoc:
+    @rbs_signatures = nil
+  end
+
   ##
   # All TopLevels known to RDoc
 
@@ -978,6 +1173,19 @@ class RDoc::Store
   end
 
   private
+
+  def remove_classes_and_modules(cms)
+    cms.each do |cm|
+      remove_classes_and_modules(cm.classes_and_modules)
+
+      if cm.is_a?(RDoc::NormalModule)
+        @modules_hash.delete(cm.full_name)
+      else
+        @classes_hash.delete(cm.full_name)
+      end
+    end
+  end
+
   def marshal_load(file)
     File.open(file, 'rb') {|io| Marshal.load(io, MarshalFilter)}
   end

data/lib/rdoc/task.rb

@@ -202,21 +202,6 @@ class RDoc::Task < Rake::TaskLib
     @options = []
   end
 
-  ##
-  # All source is inline now.  This method is deprecated
-
-  def inline_source # :nodoc:
-    warn "RDoc::Task#inline_source is deprecated"
-    true
-  end
-
-  ##
-  # All source is inline now.  This method is deprecated
-
-  def inline_source=(value) # :nodoc:
-    warn "RDoc::Task#inline_source is deprecated"
-  end
-
   ##
   # Create the tasks defined by this task lib.
 
@@ -260,6 +245,15 @@ class RDoc::Task < Rake::TaskLib
         $stderr.puts "rdoc #{args.join ' '}" if Rake.application.options.trace
         RDoc::RDoc.new.document args
       end
+
+      desc server_task_description
+      task "server" do
+        @before_running_rdoc.call if @before_running_rdoc
+        args = option_list + ["--server"] + @rdoc_files
+
+        $stderr.puts "rdoc #{args.join ' '}" if Rake.application.options.trace
+        RDoc::RDoc.new.document args
+      end
     end
 
     self
@@ -309,6 +303,13 @@ class RDoc::Task < Rake::TaskLib
     "Print RDoc coverage report"
   end
 
+  ##
+  # Task description for the server task
+
+  def server_task_description
+    "Start a live-reloading documentation server"
+  end
+
   private
 
   def rdoc_target