In Files

  • rdoc/stats.rb
  • rdoc/stats/normal.rb
  • rdoc/stats/quiet.rb
  • rdoc/stats/verbose.rb

Class/Module Index [+]

Quicksearch

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(store, 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 26
def initialize store, num_files, verbosity = 1
  @num_files = num_files
  @store     = store

  @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
             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 49
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 56
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 63
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 70
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 77
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 85
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 92
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 99
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 107
def calculate
  return if @doc_items

  ucm = @store.unique_classes_and_modules

  classes = @store.unique_classes.reject { |cm| cm.full_name == 'Object' }

  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 classes
  @num_constants,  @undoc_constants  = doc_stats constants
  @num_methods,    @undoc_methods    = doc_stats methods
  @num_modules,    @undoc_modules    = doc_stats @store.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 155
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 164
def doc_stats collection
  visible = collection.select { |item| item.display? }
  [visible.length, visible.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 172
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 182
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 189
def great_job
  report = RDoc::Markup::Document.new

  report << RDoc::Markup::Paragraph.new('100% documentation!')
  report << RDoc::Markup::Paragraph.new('Great Job!')

  report
end
            
percent_doc() click to toggle source

Calculates the percentage of items documented.

 
               # File rdoc/stats.rb, line 201
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 215
def report
  if @coverage_level > 0 then
    extend RDoc::Text
  end

  if @coverage_level.zero? then
    calculate

    return great_job if @num_items == @doc_items
  end

  ucm = @store.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|
    body = report_class_module(cm) {
      [
        report_constants(cm),
        report_attributes(cm),
        report_methods(cm),
      ].compact
    }

    report << body if body
  end

  if @coverage_level > 0 then
    calculate

    return great_job if @num_items == @doc_items
  end

  report
end
            
report_attributes(cm) click to toggle source

Returns a report on undocumented attributes in ClassModule cm

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

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

Returns a report on undocumented items in ClassModule cm

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

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

Returns a report on undocumented constants in ClassModule cm

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

Returns a report on undocumented methods in ClassModule cm

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

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

Returns a summary of the collected statistics.

 
               # File rdoc/stats.rb, line 386
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 = 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
            
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 436
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 visit Documenting-ruby.org.

blog comments powered by Disqus