rdoc 6.3.4.1 → 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
 
@@ -26,7 +39,7 @@ class RDoc::Stats
   # Creates a new Stats that will have +num_files+.  +verbosity+ defaults to 1
   # which will create an RDoc::Stats::Normal outputter.
 
-  def initialize store, num_files, verbosity = 1
+  def initialize(store, num_files, verbosity = 1)
     @num_files = num_files
     @store     = store
 
@@ -39,38 +52,45 @@ 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
 
   ##
   # Records the parsing of an alias +as+.
 
-  def add_alias as
+  def add_alias(as)
     @display.print_alias as
   end
 
   ##
   # Records the parsing of an attribute +attribute+
 
-  def add_attribute attribute
+  def add_attribute(attribute)
     @display.print_attribute attribute
   end
 
   ##
   # Records the parsing of a class +klass+
 
-  def add_class klass
+  def add_class(klass)
     @display.print_class klass
   end
 
   ##
   # Records the parsing of +constant+
 
-  def add_constant constant
+  def add_constant(constant)
     @display.print_constant constant
   end
 
@@ -155,7 +175,7 @@ class RDoc::Stats
   # 0:: Classes, modules, constants, attributes, methods
   # 1:: Level 0 + method parameters
 
-  def coverage_level= level
+  def coverage_level=(level)
     level = -1 unless level
 
     @coverage_level = level
@@ -164,7 +184,7 @@ class RDoc::Stats
   ##
   # Returns the length and number of undocumented items in +collection+.
 
-  def doc_stats collection
+  def doc_stats(collection)
     visible = collection.select { |item| item.display? }
     [visible.length, visible.count { |item| not item.documented? }]
   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.each_attribute 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
-
-    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.")
+  # 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.
 
-      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:')
+  def collect_undocumented_items
+    empty_classes = []
+    items = []
 
-      list = RDoc::Markup::List.new :BULLET
+    @store.unique_classes_and_modules.each do |class_module|
+      next unless class_module.display?
 
-      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+
-
-  def report_constants cm
-    return if cm.constants.empty?
+  # Collects undocumented attributes from +class_module+ into +items+.
 
-    report = []
+  def collect_undocumented_attributes(class_module, items)
+    class_module.attributes.each do |attr|
+      next unless attr.display?
+      next if attr.documented?
 
-    cm.each_constant 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+
-
-  def report_methods cm
-    return if cm.method_list.empty?
+  # Collects undocumented methods from +class_module+ into +items+.
+  # At coverage level > 0, also counts undocumented parameters.
 
-    report = []
+  def collect_undocumented_methods(class_module, items)
+    class_module.each_method do |method|
+      next unless method.display?
+      next if method.documented? && @coverage_level.zero?
 
-    cm.each_method do |method|
-      next if method.documented? and @coverage_level.zero?
+      undoc_param_names = nil
 
-      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,24 +445,21 @@ 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
 
   ##
   # Determines which parameters in +method+ were not documented.  Returns a
   # total parameter count and an Array of undocumented methods.
 
-  def undoc_params method
+  def undoc_params(method)
     @formatter ||= RDoc::Markup::ToTtOnly.new
 
     params = method.param_list
@@ -454,9 +477,8 @@ class RDoc::Stats
     [params.length, undoc]
   end
 
-  autoload :Quiet,   'rdoc/stats/quiet'
-  autoload :Normal,  'rdoc/stats/normal'
-  autoload :Verbose, 'rdoc/stats/verbose'
+  autoload :Quiet,   "#{__dir__}/stats/quiet"
+  autoload :Normal,  "#{__dir__}/stats/normal"
+  autoload :Verbose, "#{__dir__}/stats/verbose"
 
 end
-