Class: YARD::CLI::Stats

Inherits:
Yardoc 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:

Since:

  • 0.6.0

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

Constants inherited from YardoptsCommand

YardoptsCommand::DEFAULT_YARDOPTS_FILE

Instance Attribute Summary collapse

Attributes included from Templates::Helpers::BaseHelper

#object, #owner, #serializer

Attributes inherited from Yardoc

#apis, #assets, #excluded, #fail_on_warning, #files, #generate, #has_markup, #hidden_apis, #hidden_tags, #list, #options, #save_yardoc, #statistics, #use_cache, #visibilities

Attributes inherited from YardoptsCommand

#options_file, #use_document_file, #use_yardopts_file

Instance Method Summary collapse

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

Methods inherited from Yardoc

#parse_arguments

Methods inherited from YardoptsCommand

#parse_arguments

Methods inherited from Command

run

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:

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