rdoc-3.12 Documentation

Public Class Methods

new(num_files, verbosity = 1)

Creates a new Stats that will have num_files. verbosity defaults to 1 which will create an RDoc::Stats::Normal outputter.

# File lib/rdoc/stats.rb, line 26
def initialize num_files, verbosity = 1
  @files_so_far = 0
  @num_files = num_files

  @coverage_level = 0
  @doc_items = nil
  @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
             when 1 then Normal.new  num_files
             else        Verbose.new num_files
             end
end

Public Instance Methods

add_alias(as)

Records the parsing of an alias as.

# File lib/rdoc/stats.rb, line 48
def add_alias as
  @display.print_alias as
end

add_attribute(attribute)

Records the parsing of an attribute attribute

# File lib/rdoc/stats.rb, line 55
def add_attribute attribute
  @display.print_attribute attribute
end

add_class(klass)

Records the parsing of a class klass

# File lib/rdoc/stats.rb, line 62
def add_class klass
  @display.print_class klass
end

add_constant(constant)

Records the parsing of constant

# File lib/rdoc/stats.rb, line 69
def add_constant constant
  @display.print_constant constant
end

add_file(file)

Records the parsing of file

# File lib/rdoc/stats.rb, line 76
def add_file(file)
  @files_so_far += 1
  @display.print_file @files_so_far, file
end

add_method(method)

Records the parsing of method

# File lib/rdoc/stats.rb, line 84
def add_method(method)
  @display.print_method method
end

add_module(mod)

Records the parsing of a module mod

# File lib/rdoc/stats.rb, line 91
def add_module(mod)
  @display.print_module mod
end

begin_adding()

Call this to mark the beginning of parsing for display purposes

# File lib/rdoc/stats.rb, line 98
def begin_adding
  @display.begin_adding
end

calculate()

Calculates documentation totals and percentages for classes, modules, constants, attributes and methods.

# File lib/rdoc/stats.rb, line 106
def calculate
  return if @doc_items

  ucm = RDoc::TopLevel.unique_classes_and_modules
  constants = []
  ucm.each { |cm| constants.concat cm.constants }

  methods = []
  ucm.each { |cm| methods.concat cm.method_list }

  attributes = []
  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_constants,  @undoc_constants  = doc_stats constants
  @num_methods,    @undoc_methods    = doc_stats methods
  @num_modules,    @undoc_modules    = doc_stats RDoc::TopLevel.unique_modules

  @num_items =
    @num_attributes +
    @num_classes +
    @num_constants +
    @num_methods +
    @num_modules +
    @num_params

  @undoc_items =
    @undoc_attributes +
    @undoc_classes +
    @undoc_constants +
    @undoc_methods +
    @undoc_modules +
    @undoc_params

  @doc_items = @num_items - @undoc_items
end

coverage_level=(level)

Sets coverage report level. Accepted values are:

false or nil: No report
0: Classes, modules, constants, attributes, methods
1: Level 0 + method parameters

# File lib/rdoc/stats.rb, line 151
def coverage_level= level
  level = -1 unless level

  @coverage_level = level
end

doc_stats(collection)

Returns the length and number of undocumented items in collection.

# File lib/rdoc/stats.rb, line 160
def doc_stats collection
  visible = collection.select { |item| item.display? }
  [visible.length, visible.count { |item| not item.documented? }]
end

done_adding()

Call this to mark the end of parsing for display purposes

# File lib/rdoc/stats.rb, line 168
def done_adding
  @display.done_adding
end

fully_documented?()

The documentation status of this project. true when 100%, false when less than 100% and nil when unknown.

Set by calling calculate

# File lib/rdoc/stats.rb, line 178
def fully_documented?
  @fully_documented
end

great_job()

A report that says you did a great job!

# File lib/rdoc/stats.rb, line 185
def great_job
  report = []
  report << '100% documentation!'
  report << nil
  report << 'Great Job!'

  report.join "\n"
end

percent_doc()

Calculates the percentage of items documented.

# File lib/rdoc/stats.rb, line 197
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

report()

Returns a report on which items are not documented

# File lib/rdoc/stats.rb, line 211
def report
  if @coverage_level > 0 then
    extend RDoc::Text
  end

  report = []

  if @coverage_level.zero? then
    calculate

    return great_job if @num_items == @doc_items
  end

  ucm = RDoc::TopLevel.unique_classes_and_modules

  ucm.sort.each do |cm|
    report << report_class_module(cm) {
      [
        report_constants(cm),
        report_attributes(cm),
        report_methods(cm),
      ].compact
    }
  end

  if @coverage_level > 0 then
    calculate

    return great_job if @num_items == @doc_items
  end

  report.unshift nil
  report.unshift 'The following items are not documented:'

  report.join "\n"
end

report_attributes(cm)

Returns a report on undocumented attributes in ClassModule cm

# File lib/rdoc/stats.rb, line 251
def report_attributes cm
  return if cm.attributes.empty?

  report = []

  cm.each_attribute do |attr|
    next if attr.documented?
    report << "  #{attr.definition} :#{attr.name} "          "# in file #{attr.file.full_name}"
  end

  report
end

report_class_module(cm) { || ... }

Returns a report on undocumented items in ClassModule cm

# File lib/rdoc/stats.rb, line 268
def report_class_module cm
  return if cm.fully_documented? and @coverage_level.zero?
  return unless cm.display?

  report = []

  if cm.in_files.empty? then
    report << "# #{cm.definition} is referenced but empty."
    report << '#'
    report << '# It probably came from another project.  '          "I'm sorry I'm holding it against you."
    report << nil

    return report
  elsif cm.documented? then
    documented = true
    report << "#{cm.definition} # is documented"
  else
    report << '# in files:'

    cm.in_files.each do |file|
      report << "#   #{file.full_name}"
    end

    report << nil

    report << "#{cm.definition}"
  end

  body = yield.flatten # HACK remove #flatten

  return if body.empty? and documented

  report << nil << body unless body.empty?

  report << 'end'
  report << nil

  report
end

report_constants(cm)

Returns a report on undocumented constants in ClassModule cm

# File lib/rdoc/stats.rb, line 312
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
    report << "  # in file #{constant.file.full_name}"
    report << "  #{constant.name} = nil"
  end

  report
end

report_methods(cm)

Returns a report on undocumented methods in ClassModule cm

# File lib/rdoc/stats.rb, line 331
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"
      end
    end

    next if method.documented? and not param_report
    report << "  # in file #{method.file.full_name}"
    report << param_report if param_report
    scope = method.singleton ? 'self.' : nil
    report << "  def #{scope}#{method.name}#{method.params}; end"
    report << nil
  end

  report
end

summary()

Returns a summary of the collected statistics.

# File lib/rdoc/stats.rb, line 366
def summary
  calculate

  num_width = [@num_files, @num_items].max.to_s.length
  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 << nil

  report << 'Classes:    %*d (%*d undocumented)' % [
    num_width, @num_classes, undoc_width, @undoc_classes]
  report << 'Modules:    %*d (%*d undocumented)' % [
    num_width, @num_modules, undoc_width, @undoc_modules]
  report << 'Constants:  %*d (%*d undocumented)' % [
    num_width, @num_constants, undoc_width, @undoc_constants]
  report << 'Attributes: %*d (%*d undocumented)' % [
    num_width, @num_attributes, undoc_width, @undoc_attributes]
  report << 'Methods:    %*d (%*d undocumented)' % [
    num_width, @num_methods, undoc_width, @undoc_methods]
  report << 'Parameters: %*d (%*d undocumented)' % [
    num_width, @num_params, undoc_width, @undoc_params] if
      @coverage_level > 0

  report << nil

  report << 'Total:      %*d (%*d undocumented)' % [
    num_width, @num_items, undoc_width, @undoc_items]

  report << '%6.2f%% documented' % percent_doc
  report << nil
  report << 'Elapsed: %0.1fs' % (Time.now - @start)

  report.join "\n"
end

undoc_params(method)

Determines which parameters in method were not documented. Returns a total parameter count and an Array of undocumented methods.

# File lib/rdoc/stats.rb, line 415
def undoc_params method
  @formatter ||= RDoc::Markup::ToTtOnly.new

  params = method.param_list

  return 0, [] if params.empty?

  document = parse method.comment

  tts = document.accept @formatter

  undoc = params - tts

  [params.length, undoc]
end

/	Search
?	Show this help

Keyboard Shortcuts