Class: RDoc::Stats

### Home Classes Methods

### In Files

- lib/rdoc/stats.rb

### Parent

Object

### Namespace

- CLASS RDoc::Stats::Normal
- CLASS RDoc::Stats::Quiet
- CLASS RDoc::Stats::Verbose

### Methods

- ::new
- #add_alias
- #add_attribute
- #add_class
- #add_constant
- #add_file
- #add_method
- #add_module
- #begin_adding
- #calculate
- #coverage_level=
- #doc_stats
- #done_adding
- #fully_documented?
- #great_job
- #percent_doc
- #report
- #report_attributes
- #report_class_module
- #report_constants
- #report_methods
- #summary
- #undoc_params

### Included Modules

- RDoc::Text

### Files

- CONTRIBUTING.rdoc
- CVE-2013-0256.rdoc
- ExampleRDoc.rdoc
- LICENSE.rdoc
- Manifest.txt
- README.rdoc
- RI.rdoc
- Rakefile
- TODO.rdoc

### Class/Module Index

Quicksearch

- RDoc
- RDoc::Alias
- RDoc::AnonClass
- RDoc::AnyMethod
- RDoc::Attr
- RDoc::ClassModule
- RDoc::CodeObject
- RDoc::Comment
- RDoc::Constant
- RDoc::Context
- RDoc::Context::Section
- RDoc::CrossReference
- RDoc::ERBIO
- RDoc::ERBPartial
- RDoc::Encoding
- RDoc::Error
- RDoc::Extend
- RDoc::Gauntlet
- RDoc::Generator
- RDoc::Generator::Darkfish
- RDoc::Generator::JsonIndex
- RDoc::Generator::Markup
- RDoc::Generator::POT
- RDoc::Generator::RI
- RDoc::GhostMethod
- RDoc::Include
- RDoc::Markdown
- RDoc::Markdown::Literals
- RDoc::Markup
- RDoc::Markup::AttrChanger
- RDoc::Markup::AttrSpan
- RDoc::Markup::AttributeManager
- RDoc::Markup::Attributes
- RDoc::Markup::BlankLine
- RDoc::Markup::BlockQuote
- RDoc::Markup::Document
- RDoc::Markup::Formatter
- RDoc::Markup::FormatterTestCase
- RDoc::Markup::HardBreak
- RDoc::Markup::Include
- RDoc::Markup::IndentedParagraph
- RDoc::Markup::List
- RDoc::Markup::ListItem
- RDoc::Markup::Paragraph
- RDoc::Markup::Parser
- RDoc::Markup::Parser::Error
- RDoc::Markup::Parser::ParseError
- RDoc::Markup::PreProcess
- RDoc::Markup::Raw
- RDoc::Markup::Rule
- RDoc::Markup::Special
- RDoc::Markup::TextFormatterTestCase
- RDoc::Markup::ToAnsi
- RDoc::Markup::ToBs
- RDoc::Markup::ToHtml
- RDoc::Markup::ToHtmlCrossref
- RDoc::Markup::ToHtmlSnippet
- RDoc::Markup::ToJoinedParagraph
- RDoc::Markup::ToLabel
- RDoc::Markup::ToMarkdown
- RDoc::Markup::ToRdoc
- RDoc::Markup::ToTableOfContents
- RDoc::Markup::ToTest
- RDoc::Markup::ToTtOnly
- RDoc::Markup::Verbatim
- RDoc::MetaMethod
- RDoc::MethodAttr
- RDoc::Mixin
- RDoc::NormalClass
- RDoc::NormalModule
- RDoc::Options
- RDoc::Parser
- RDoc::Parser::C
- RDoc::Parser::ChangeLog
- RDoc::Parser::Markdown
- RDoc::Parser::RD
- RDoc::Parser::Ruby
- RDoc::Parser::RubyTools
- RDoc::Parser::Simple
- RDoc::Parser::Text
- RDoc::RD
- RDoc::RD::BlockParser
- RDoc::RD::Inline
- RDoc::RD::InlineParser
- RDoc::RDoc
- RDoc::RI
- RDoc::RI::Driver
- RDoc::RI::Driver::Error
- RDoc::RI::Driver::NotFoundError
- RDoc::RI::Error
- RDoc::RI::Paths
- RDoc::Require
- RDoc::RubyLex
- RDoc::RubyLex::Error
- RDoc::RubyToken
- RDoc::RubygemsHook
- RDoc::Servlet
- RDoc::SingleClass
- RDoc::Stats
- RDoc::Stats::Normal
- RDoc::Stats::Quiet
- RDoc::Stats::Verbose
- RDoc::Store
- RDoc::Store::Error
- RDoc::Store::MissingFileError
- RDoc::Task
- RDoc::Task
- RDoc::TestCase
- RDoc::TokenStream
- RDoc::TomDoc
- RDoc::TopLevel
- Object

No matching classes.

# 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 lib/rdoc/stats.rb, line 28
    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 lib/rdoc/stats.rb, line 51
    def add_alias as
      @display.print_alias as
    end

add_attribute(attribute) click to toggle source

Records the parsing of an attribute `attribute`

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

add_class(klass) click to toggle source

Records the parsing of a class `klass`

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

add_constant(constant) click to toggle source

Records the parsing of `constant`

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

add_file(file) click to toggle source

Records the parsing of `file`

    # File lib/rdoc/stats.rb, line 79
    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 lib/rdoc/stats.rb, line 87
    def add_method(method)
      @display.print_method method
    end

add_module(mod) click to toggle source

Records the parsing of a module `mod`

    # File lib/rdoc/stats.rb, line 94
    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 lib/rdoc/stats.rb, line 101
    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 lib/rdoc/stats.rb, line 109
    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 lib/rdoc/stats.rb, line 157
    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 lib/rdoc/stats.rb, line 166
    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 lib/rdoc/stats.rb, line 174
    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 lib/rdoc/stats.rb, line 184
    def fully_documented?
      @fully_documented
    end

great_job() click to toggle source

A report that says you did a great job!

    # File lib/rdoc/stats.rb, line 191
    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 lib/rdoc/stats.rb, line 203
    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 lib/rdoc/stats.rb, line 217
    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 lib/rdoc/stats.rb, line 258
    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 lib/rdoc/stats.rb, line 276
    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 lib/rdoc/stats.rb, line 328
    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 lib/rdoc/stats.rb, line 350
    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 lib/rdoc/stats.rb, line 388
    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 lib/rdoc/stats.rb, line 438
    def undoc_params method
      @formatter ||= RDoc::Markup::ToTtOnly.new

      params = method.param_list

      params = params.map { |param| param.gsub(/^\*\*?/, '') }

      return 0, [] if params.empty?

      document = parse method.comment

      tts = document.accept @formatter

      undoc = params - tts

      [params.length, undoc]
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.