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, :methods]

Constants inherited from Yardoc

Yardoc::DEFAULT_YARDOPTS_FILE

Instance Attribute Summary collapse

Attributes included from Templates::Helpers::BaseHelper

#object, #serializer

Attributes inherited from Yardoc

#assets, #excluded, #files, #generate, #hidden_tags, #list, #options, #options_file, #save_yardoc, #statistics, #use_cache, #use_document_file, #use_yardopts_file, #visibilities

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, #yardopts

Methods inherited from Command

#common_options, #load_script, #parse_options, 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



17
18
19
20
21
22
 
# File 'lib/yard/cli/stats.rb', line 17

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



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

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



96
97
98
 
# File 'lib/yard/cli/stats.rb', line 96

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

#description ⇒ Object

Since:

  • 0.6.0



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

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



140
141
142
143
144
145
146
147
148
149
 
# File 'lib/yard/cli/stats.rb', line 140

def output(name, data, undoc = nil)
  @total += data if data.is_a?(Integer) && undoc
  @undocumented += undoc if undoc.is_a?(Integer)
  if undoc
    data = ("% 5s (% 5d undocumented)" % [data, undoc])
  else
    data = "% 5s" % data
  end
  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



53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/yard/cli/stats.rb', line 53

def print_statistics
  @total, @undocumented = 0, 0
  meths = methods.map {|m| m.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 = (@total - @undocumented).to_f / @total.to_f * 100
  puts("% 3.2f%% documented" % total)
end

#print_undocumented_objects ⇒ Object

Prints list of undocumented objects

Since:

  • 0.6.0



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/yard/cli/stats.rb', line 69

def print_undocumented_objects
  return if !@undoc_list || @undoc_list.empty?
  puts
  puts "Undocumented Objects:"
  
  objects = @undoc_list.sort_by {|o| o.file }
  max = objects.sort_by {|o| o.path.length }.last.path.length
  if @compact
    objects.each do |object|
      puts("%-#{max}s     (%s)" % [object.path, object.file])
    end
  else
    last_file = nil
    objects.each do |object|
      if object.file != last_file
        puts
        puts "(in file: #{object.file})"
      end
      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



33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
 
# File 'lib/yard/cli/stats.rb', line 33

def run(*args)
  parse_arguments(*args)

  if parse
    if use_cache
      Registry.load!
      checksums = Registry.checksums.dup
    end
    YARD.parse(files, excluded)
    Registry.save(use_cache) if save_yardoc
  end
  
  print_statistics
  print_undocumented_objects
end

#stats_for_classes ⇒ Object

Statistics for classes

Since:

  • 0.6.0



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

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

#stats_for_constants ⇒ Object

Statistics for constants

Since:

  • 0.6.0



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

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

#stats_for_files ⇒ Object

Statistics for files

Since:

  • 0.6.0



101
102
103
104
105
 
# File 'lib/yard/cli/stats.rb', line 101

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



123
124
125
126
127
128
129
 
# File 'lib/yard/cli/stats.rb', line 123

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

#stats_for_modules ⇒ Object

Statistics for modules

Since:

  • 0.6.0



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

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