RDoc::Stats

RDoc statistics collector which prints a summary and report of a project's documentation totals.

Attributes

coverage_level[R]

Output level for the coverage report

files_so_far[R]

Count of files parsed during parsing

num_files[R]

Total number of files found

Public Class Methods

new(num_files, verbosity = 1) click to toggle source

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

 
               # File rdoc/stats.rb, line 28
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) click to toggle source

Records the parsing of an alias as.

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

add_attribute(attribute) click to toggle source

Records the parsing of an attribute attribute

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

add_class(klass) click to toggle source

Records the parsing of a class klass

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

add_constant(constant) click to toggle source

Records the parsing of constant

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

add_file(file) click to toggle source

Records the parsing of file

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

add_method(method) click to toggle source

Records the parsing of method

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

add_module(mod) click to toggle source

Records the parsing of a module mod

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

begin_adding() click to toggle source

Call this to mark the beginning of parsing for display purposes

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

calculate() click to toggle source

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

 
               # File rdoc/stats.rb, line 108
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) click to toggle source

Sets coverage report level. Accepted values are:

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

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

  @coverage_level = level
end

doc_stats(collection) click to toggle source

Returns the length and number of undocumented items in collection.

 
               # File rdoc/stats.rb, line 162
def doc_stats collection
  [collection.length, collection.count { |item| not item.documented? }]
end

done_adding() click to toggle source

Call this to mark the end of parsing for display purposes

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

fully_documented?() click to toggle source

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

Set by calling calculate

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

great_job() click to toggle source

A report that says you did a great job!

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

  report.join "\n"
end

percent_doc() click to toggle source

Calculates the percentage of items documented.

 
               # File rdoc/stats.rb, line 198
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() click to toggle source

Returns a report on which items are not documented

 
               # File rdoc/stats.rb, line 212
def report
  if @coverage_level > 0 then
    require 'rdoc/markup/to_tt_only'
    require 'rdoc/generator/markup'
    require 'rdoc/text'
    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) click to toggle source

Returns a report on undocumented attributes in ClassModule cm

 
               # File rdoc/stats.rb, line 255
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) click to toggle source

Returns a report on undocumented items in ClassModule cm

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

  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) click to toggle source

Returns a report on undocumented constants in ClassModule cm

 
               # File rdoc/stats.rb, line 315
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) click to toggle source

Returns a report on undocumented methods in ClassModule cm

 
               # File rdoc/stats.rb, line 334
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
    report << "  def #{method.name}#{method.params}; end"
    report << nil
  end

  report
end

summary() click to toggle source

Returns a summary of the collected statistics.

 
               # File rdoc/stats.rb, line 368
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) click to toggle source

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

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

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please see Improve the docs, or visit Documenting-ruby.org.

Home Classes Methods

In Files

Parent

Namespace

Methods

Class/Module Index

RDoc::Stats

Attributes

Public Class Methods

Public Instance Methods