rdoc 3.1 → 6.3.3

data/lib/rdoc/stats/normal.rb

@@ -1,3 +1,11 @@
+# frozen_string_literal: true
+begin
+  require 'io/console/size'
+rescue LoadError
+  # for JRuby
+  require 'io/console'
+end
+
 ##
 # Stats printer that prints just the files being documented with a progress
 # bar
@@ -6,6 +14,7 @@ class RDoc::Stats::Normal < RDoc::Stats::Quiet
 
   def begin_adding # :nodoc:
     puts "Parsing sources..."
+    @last_width = 0
   end
 
   ##
@@ -17,11 +26,12 @@ class RDoc::Stats::Normal < RDoc::Stats::Quiet
                            files_so_far,
                            @num_files)
 
-    if $stdout.tty? then
+    if $stdout.tty?
       # Print a progress bar, but make sure it fits on a single line. Filename
       # will be truncated if necessary.
-      terminal_width = (ENV['COLUMNS'] || 80).to_i
-      max_filename_size = terminal_width - progress_bar.size
+      size = IO.respond_to?(:console_size) ? IO.console_size : IO.console.winsize
+      terminal_width = size[1].to_i.nonzero? || 80
+      max_filename_size = (terminal_width - progress_bar.size) - 1
 
       if filename.size > max_filename_size then
         # Turn "some_long_filename.rb" to "...ong_filename.rb"
@@ -29,17 +39,15 @@ class RDoc::Stats::Normal < RDoc::Stats::Quiet
         filename[0..2] = "..."
       end
 
-      # Pad the line with whitespaces so that leftover output from the
+      # Clean the line with whitespaces so that leftover output from the
       # previous line doesn't show up.
-      line = "#{progress_bar}#{filename}"
-      padding = terminal_width - line.size
-      line << (" " * padding) if padding > 0
-
-      $stdout.print("#{line}\r")
+      $stdout.print("\r\e[K") if @last_width && @last_width > 0
+      @last_width = progress_bar.size + filename.size
+      term = "\r"
     else
-      $stdout.puts "#{progress_bar} #{filename}"
+      term = "\n"
     end
-
+    $stdout.print(progress_bar, filename, term)
     $stdout.flush
   end
 
@@ -48,4 +56,3 @@ class RDoc::Stats::Normal < RDoc::Stats::Quiet
   end
 
 end
-

data/lib/rdoc/stats/quiet.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 ##
 # Stats printer that prints nothing
 

data/lib/rdoc/stats/verbose.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 ##
 # Stats printer that prints everything documented, including the documented
 # status

data/lib/rdoc/stats.rb

@@ -1,11 +1,17 @@
-require 'rdoc'
-
+# frozen_string_literal: true
 ##
 # RDoc statistics collector which prints a summary and report of a project's
 # documentation totals.
 
 class RDoc::Stats
 
+  include RDoc::Text
+
+  ##
+  # Output level for the coverage report
+
+  attr_reader :coverage_level
+
   ##
   # Count of files parsed during parsing
 
@@ -20,13 +26,18 @@ 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 num_files, verbosity = 1
-    @files_so_far = 0
+  def initialize store, num_files, verbosity = 1
     @num_files = num_files
-    @fully_documented = nil
-    @percent_doc = nil
+    @store     = store
 
-    @start = Time.now
+    @coverage_level   = 0
+    @doc_items        = nil
+    @files_so_far     = 0
+    @fully_documented = false
+    @num_params       = 0
+    @percent_doc      = nil
+    @start            = Time.now
+    @undoc_params     = 0
 
     @display = case verbosity
                when 0 then Quiet.new   num_files
@@ -93,12 +104,16 @@ class RDoc::Stats
   end
 
   ##
-  # Calculates documentation totals and percentages
+  # Calculates documentation totals and percentages for classes, modules,
+  # constants, attributes and methods.
 
   def calculate
-    return if @percent_doc
+    return if @doc_items
+
+    ucm = @store.unique_classes_and_modules
+
+    classes = @store.unique_classes.reject { |cm| cm.full_name == 'Object' }
 
-    ucm = RDoc::TopLevel.unique_classes_and_modules
     constants = []
     ucm.each { |cm| constants.concat cm.constants }
 
@@ -109,37 +124,49 @@ class RDoc::Stats
     ucm.each { |cm| attributes.concat cm.attributes }
 
     @num_attributes, @undoc_attributes = doc_stats attributes
-    @num_classes,    @undoc_classes    = doc_stats RDoc::TopLevel.unique_classes
+    @num_classes,    @undoc_classes    = doc_stats classes
     @num_constants,  @undoc_constants  = doc_stats constants
     @num_methods,    @undoc_methods    = doc_stats methods
-    @num_modules,    @undoc_modules    = doc_stats RDoc::TopLevel.unique_modules
+    @num_modules,    @undoc_modules    = doc_stats @store.unique_modules
 
     @num_items =
       @num_attributes +
       @num_classes +
       @num_constants +
       @num_methods +
-      @num_modules
+      @num_modules +
+      @num_params
 
     @undoc_items =
       @undoc_attributes +
       @undoc_classes +
       @undoc_constants +
       @undoc_methods +
-      @undoc_modules
+      @undoc_modules +
+      @undoc_params
 
     @doc_items = @num_items - @undoc_items
+  end
 
-    @fully_documented = (@num_items - @doc_items) == 0
+  ##
+  # Sets coverage report level.  Accepted values are:
+  #
+  # false or nil:: No report
+  # 0:: Classes, modules, constants, attributes, methods
+  # 1:: Level 0 + method parameters
 
-    @percent_doc = @doc_items.to_f / @num_items * 100 if @num_items.nonzero?
+  def coverage_level= level
+    level = -1 unless level
+
+    @coverage_level = level
   end
 
   ##
   # Returns the length and number of undocumented items in +collection+.
 
   def doc_stats collection
-    [collection.length, collection.count { |item| not item.documented? }]
+    visible = collection.select { |item| item.display? }
+    [visible.length, visible.count { |item| not item.documented? }]
   end
 
   ##
@@ -159,97 +186,201 @@ 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.
+
+  def percent_doc
+    return @percent_doc if @percent_doc
+
+    @fully_documented = (@num_items - @doc_items) == 0
+
+    @percent_doc = @doc_items.to_f / @num_items * 100 if @num_items.nonzero?
+    @percent_doc ||= 0
+
+    @percent_doc
+  end
+
   ##
   # Returns a report on which items are not documented
 
   def report
-    report = []
-
-    calculate
+    if @coverage_level > 0 then
+      extend RDoc::Text
+    end
 
-    if @num_items == @doc_items then
-      report << '100% documentation!'
-      report << nil
-      report << 'Great Job!'
+    if @coverage_level.zero? then
+      calculate
 
-      return report.join "\n"
+      return great_job if @num_items == @doc_items
     end
 
-    report << 'The following items are not documented:'
-    report << nil
+    ucm = @store.unique_classes_and_modules
 
-    ucm = RDoc::TopLevel.unique_classes_and_modules
+    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|
-      type = case cm # TODO #definition
-             when RDoc::NormalClass  then 'class'
-             when RDoc::SingleClass  then 'class <<'
-             when RDoc::NormalModule then 'module'
-             end
-
-      if cm.fully_documented? then
-        next
-      elsif cm.in_files.empty? or
-            (cm.constants.empty? and cm.method_list.empty?) then
-        report << "# #{type} #{cm.full_name} is referenced but empty."
-        report << '#'
-        report << '# It probably came from another project.  ' \
-                  'I\'m sorry I\'m holding it against you.'
-        report << nil
-
-        next
-      elsif cm.documented? then
-        report << "#{type} #{cm.full_name} # is documented"
-      else
-        report << '# in files:'
-
-        cm.in_files.each do |file|
-          report << "#   #{file.full_name}"
-        end
+      body = report_class_module(cm) {
+        [
+          report_constants(cm),
+          report_attributes(cm),
+          report_methods(cm),
+        ].compact
+      }
+
+      report << body if body
+    end
 
-        report << nil
+    if @coverage_level > 0 then
+      calculate
 
-        report << "#{type} #{cm.full_name}"
-      end
+      return great_job if @num_items == @doc_items
+    end
 
-      unless cm.constants.empty? then
-        report << nil
+    report
+  end
 
-        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
-          report << "  # in file #{constant.file.full_name}"
-          report << "  #{constant.name} = nil"
-        end
-      end
+  ##
+  # Returns a report on undocumented attributes in ClassModule +cm+
 
-      unless cm.attributes.empty? then
-        report << nil
+  def report_attributes cm
+    return if cm.attributes.empty?
 
-        cm.each_attribute do |attr|
-          next if attr.documented?
-          report << "  #{attr.definition} #{attr.name} " \
-                    "# in file #{attr.file.full_name}"
-        end
+    report = []
+
+    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
+
+    report
+  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.")
+
+      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:')
+
+      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)
       end
 
-      unless cm.method_list.empty? then
-        report << nil
+      report << list
+      report << RDoc::Markup::BlankLine.new
+
+      klass = RDoc::Markup::Verbatim.new("#{cm.definition}\n")
+    end
+
+    klass << "\n"
+
+    body = yield.flatten # HACK remove #flatten
+
+    if body.empty? then
+      return if documented
+
+      klass.parts.pop
+    else
+      klass.parts.concat body
+    end
+
+    klass << "end\n"
+
+    report << klass
+
+    report
+  end
+
+  ##
+  # Returns a report on undocumented constants in ClassModule +cm+
+
+  def report_constants cm
+    return if cm.constants.empty?
+
+    report = []
+
+    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
+
+      line = constant.line ? ":#{constant.line}" : line
+      report << "  # in file #{constant.file.full_name}#{line}\n"
+      report << "  #{constant.name} = nil\n"
+      report << "\n"
+    end
+
+    report
+  end
 
-        cm.each_method do |method|
-          next if method.documented?
-          report << "  # in file #{method.file.full_name}"
-          report << "  def #{method.name}#{method.params}; end"
-          report << nil
+  ##
+  # Returns a report on undocumented methods in ClassModule +cm+
+
+  def report_methods cm
+    return if cm.method_list.empty?
+
+    report = []
+
+    cm.each_method do |method|
+      next if method.documented? and @coverage_level.zero?
+
+      if @coverage_level > 0 then
+        params, undoc = undoc_params method
+
+        @num_params += params
+
+        unless undoc.empty? then
+          @undoc_params += undoc.length
+
+          undoc = undoc.map do |param| "+#{param}+" end
+          param_report = "  # #{undoc.join ', '} is not documented\n"
         end
       end
 
-      report << 'end'
-      report << nil
+      next if method.documented? and not param_report
+
+      line = method.line ? ":#{method.line}" : nil
+      scope = method.singleton ? 'self.' : nil
+
+      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
 
-    report.join "\n"
+    report
   end
 
   ##
@@ -259,41 +390,68 @@ class RDoc::Stats
     calculate
 
     num_width = [@num_files, @num_items].max.to_s.length
-    nodoc_width = [
+    undoc_width = [
       @undoc_attributes,
       @undoc_classes,
       @undoc_constants,
       @undoc_items,
       @undoc_methods,
       @undoc_modules,
+      @undoc_params,
     ].max.to_s.length
 
-    report = []
-    report << 'Files:      %*d' % [num_width, @num_files]
+    report = RDoc::Markup::Verbatim.new
+
+    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" % [
+      num_width, @num_modules, undoc_width, @undoc_modules]
+    report << "Constants:  %*d (%*d undocumented)\n" % [
+      num_width, @num_constants, undoc_width, @undoc_constants]
+    report << "Attributes: %*d (%*d undocumented)\n" % [
+      num_width, @num_attributes, undoc_width, @undoc_attributes]
+    report << "Methods:    %*d (%*d undocumented)\n" % [
+      num_width, @num_methods, undoc_width, @undoc_methods]
+    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
+  end
+
+  ##
+  # Determines which parameters in +method+ were not documented.  Returns a
+  # total parameter count and an Array of undocumented methods.
+
+  def undoc_params method
+    @formatter ||= RDoc::Markup::ToTtOnly.new
+
+    params = method.param_list
 
-    report << nil
+    params = params.map { |param| param.gsub(/^\*\*?/, '') }
 
-    report << 'Classes:    %*d (%*d undocumented)' % [
-      num_width, @num_classes, nodoc_width, @undoc_classes]
-    report << 'Modules:    %*d (%*d undocumented)' % [
-      num_width, @num_modules, nodoc_width, @undoc_modules]
-    report << 'Constants:  %*d (%*d undocumented)' % [
-      num_width, @num_constants, nodoc_width, @undoc_constants]
-    report << 'Attributes: %*d (%*d undocumented)' % [
-      num_width, @num_attributes, nodoc_width, @undoc_attributes]
-    report << 'Methods:    %*d (%*d undocumented)' % [
-      num_width, @num_methods, nodoc_width, @undoc_methods]
+    return 0, [] if params.empty?
 
-    report << nil
+    document = parse method.comment
 
-    report << 'Total:      %*d (%*d undocumented)' % [
-      num_width, @num_items, nodoc_width, @undoc_items]
+    tts = document.accept @formatter
 
-    report << '%6.2f%% documented' % @percent_doc if @percent_doc
-    report << nil
-    report << 'Elapsed: %0.1fs' % (Time.now - @start)
+    undoc = params - tts
 
-    report.join "\n"
+    [params.length, undoc]
   end
 
   autoload :Quiet,   'rdoc/stats/quiet'