# Class: YARD::CLI::Stats

Inherits:
  Yardoc
  - Object
  - Command
  - YardoptsCommand
  - Yardoc
  - YARD::CLI::Stats
  show all

Includes:
  Templates::Helpers::BaseHelper

Defined in:
  lib/yard/cli/stats.rb

## Overview

Since:

- 0.6.0

## Constant Summary collapse

STATS_ORDER =

Maintains the order in which `stats_for_` statistics methods should be printed.

See Also:

- #print_statistics

Since:

- 0.6.0

      [:files, :modules, :classes, :constants, :attributes, :methods]

## Instance Attribute Summary collapse

- #parse ⇒ Boolean

  Whether to parse and load registry.

### Attributes included from Templates::Helpers::BaseHelper

#object, #owner, #serializer

## Instance Method Summary collapse

- #all_objects ⇒ Array<CodeObjects::Base>

  All the parsed objects in the registry, removing any objects that are not visible (private, protected) depending on the arguments passed to the command.

- #description ⇒ Object
- #initialize(parse = true) ⇒ Stats constructor

  A new instance of Stats.

- #output(name, data, undoc = nil) ⇒ void

  Prints a statistic to standard out.

- #print_statistics ⇒ Object

  Prints statistics for different object types.

- #print_undocumented_objects ⇒ Object

  Prints list of undocumented objects.

- #run(*args) ⇒ void

  Runs the commandline utility, parsing arguments and generating output if set.

- #stats_for_attributes ⇒ Object

  Statistics for attributes.

- #stats_for_classes ⇒ Object

  Statistics for classes.

- #stats_for_constants ⇒ Object

  Statistics for constants.

- #stats_for_files ⇒ Object

  Statistics for files.

- #stats_for_methods ⇒ Object

  Statistics for methods.

- #stats_for_modules ⇒ Object

  Statistics for modules.

### Methods included from Templates::Helpers::BaseHelper

#format_object_title, #format_object_type, #format_source, #format_types, #globals, #h, #link_file, #link_include_file, #link_include_object, #link_object, #link_url, #linkify, #run_verifier

## Constructor Details

### #initialize(parse = true) ⇒ `Stats`

Returns a new instance of Stats.

Parameters:

- parse (`Boolean`) (defaults to: `true`) —

  whether to parse and load registry (see #parse)

Since:

- 0.6.0

    18
    19
    20
    21
    22
    23

    # File 'lib/yard/cli/stats.rb', line 18

    def initialize(parse = true)
      super()
      @parse = parse
      @undoc_list = nil
      @compact = false
    end

## Instance Attribute Details

### #parse ⇒ `Boolean`

Returns whether to parse and load registry.

Returns:

- (`Boolean`) —

  whether to parse and load registry

Since:

- 0.6.0

    15
    16
    17

    # File 'lib/yard/cli/stats.rb', line 15

    def parse
      @parse
    end

## Instance Method Details

### #all_objects ⇒ `Array<CodeObjects::Base>`

Returns all the parsed objects in the registry, removing any objects that are not visible (private, protected) depending on the arguments passed to the command.

Returns:

- (`Array<CodeObjects::Base>`) —

  all the parsed objects in the registry, removing any objects that are not visible (private, protected) depending on the arguments passed to the command.

Since:

- 0.6.0

    108
    109
    110

    # File 'lib/yard/cli/stats.rb', line 108

    def all_objects
      @all_objects ||= run_verifier Registry.all
    end

### #description ⇒ `Object`

Since:

- 0.6.0

    25
    26
    27

    # File 'lib/yard/cli/stats.rb', line 25

    def description
      "Prints documentation statistics on a set of files"
    end

### #output(name, data, undoc = nil) ⇒ `void`

This method returns an undefined value.

Prints a statistic to standard out. This method is optimized for getting Integer values, though it allows any data to be printed.

Parameters:

- name (`String`) —

  the statistic name

- data (`Integer`, `String`) —

  the numeric (or any) data representing the statistic. If `data` is an Integer, it should represent the total objects of a type.

- undoc (`Integer`, `nil`) (defaults to: `nil`) —

  number of undocumented objects for the type

Since:

- 0.6.0

    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172

    # File 'lib/yard/cli/stats.rb', line 162

    def output(name, data, undoc = nil)
      @total += data if data.is_a?(Integer) && undoc
      @undocumented += undoc if undoc.is_a?(Integer)
      data =
        if undoc
          ("%5s (% 5d undocumented)" % [data, undoc])
        else
          "%5s" % data
        end
      log.puts("%-12s %s" % [name + ":", data])
    end

### #print_statistics ⇒ `Object`

Prints statistics for different object types

To add statistics for a specific type, add a method `#stats_for_TYPE` to this class that calls #output.

Since:

- 0.6.0

    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76

    # File 'lib/yard/cli/stats.rb', line 54

    def print_statistics
      @total = 0
      @undocumented = 0
      meths = methods.map(&:to_s).grep(/^stats_for_/)
      STATS_ORDER.each do |meth|
        mname = "stats_for_#{meth}"
        if meths.include?(mname)
          send(mname)
          meths.delete(mname)
        end
      end
      meths.each {|m| send(m) }

      total =
        if @undocumented == 0
          100
        elsif @total == 0
          0
        else
          (@total - @undocumented).to_f / @total.to_f * 100
        end
      log.puts("% 3.2f%% documented" % total)
    end

### #print_undocumented_objects ⇒ `Object`

Prints list of undocumented objects

Since:

- 0.6.0

    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103

    # File 'lib/yard/cli/stats.rb', line 79

    def print_undocumented_objects
      return if !@undoc_list || @undoc_list.empty?
      log.puts
      log.puts "Undocumented Objects:"

      # array needed for sort due to unstable sort
      objects = @undoc_list.sort_by {|o| [o.file.to_s, o.path] }
      max = objects.max {|a, b| a.path.length <=> b.path.length }.path.length
      if @compact
        objects.each do |object|
          log.puts("%-#{max}s     (%s)" % [object.path,
            [object.file || "-unknown-", object.line].compact.join(":")])
        end
      else
        last_file = nil
        objects.each do |object|
          if object.file != last_file
            log.puts
            log.puts "(in file: #{object.file || "-unknown-"})"
          end
          log.puts object.path
          last_file = object.file
        end
      end
    end

### #run(*args) ⇒ `void`

This method returns an undefined value.

Runs the commandline utility, parsing arguments and generating output if set.

Parameters:

- args (`Array<String>`) —

  the list of arguments

Since:

- 0.6.0

    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48

    # File 'lib/yard/cli/stats.rb', line 34

    def run(*args)
      parse_arguments(*args)

      if use_cache
        Registry.load!
      elsif parse
        YARD.parse(files, excluded)
        Registry.save(use_cache) if save_yardoc
      end

      print_statistics
      print_undocumented_objects

      abort if fail_on_warning && log.warned
    end

### #stats_for_attributes ⇒ `Object`

Statistics for attributes

Since:

- 0.6.0

    135
    136
    137
    138
    139
    140
    141

    # File 'lib/yard/cli/stats.rb', line 135

    def stats_for_attributes
      objs = all_objects.select {|m| m.type == :method && m.is_attribute? }
      objs.uniq! {|m| m.name.to_s.gsub(/=$/, '') }
      undoc = objs.select {|m| m.docstring.blank? }
      @undoc_list |= undoc if @undoc_list
      output "Attributes", objs.size, undoc.size
    end

### #stats_for_classes ⇒ `Object`

Statistics for classes

Since:

- 0.6.0

    125
    126
    127

    # File 'lib/yard/cli/stats.rb', line 125

    def stats_for_classes
      output "Classes", *type_statistics(:class)
    end

### #stats_for_constants ⇒ `Object`

Statistics for constants

Since:

- 0.6.0

    130
    131
    132

    # File 'lib/yard/cli/stats.rb', line 130

    def stats_for_constants
      output "Constants", *type_statistics(:constant)
    end

### #stats_for_files ⇒ `Object`

Statistics for files

Since:

- 0.6.0

    113
    114
    115
    116
    117

    # File 'lib/yard/cli/stats.rb', line 113

    def stats_for_files
      files = []
      all_objects.each {|o| files |= [o.file] }
      output "Files", files.size
    end

### #stats_for_methods ⇒ `Object`

Statistics for methods

Since:

- 0.6.0

    144
    145
    146
    147
    148
    149
    150
    151

    # File 'lib/yard/cli/stats.rb', line 144

    def stats_for_methods
      objs = all_objects.select {|m| m.type == :method }
      objs.reject!(&:is_alias?)
      objs.reject!(&:is_attribute?)
      undoc = objs.select {|m| m.docstring.blank? }
      @undoc_list |= undoc if @undoc_list
      output "Methods", objs.size, undoc.size
    end

### #stats_for_modules ⇒ `Object`

Statistics for modules

Since:

- 0.6.0

    120
    121
    122

    # File 'lib/yard/cli/stats.rb', line 120

    def stats_for_modules
      output "Modules", *type_statistics(:module)
    end