Class: YARD::CLI::Stats

Inherits:
Yardoc show all
Includes:
Templates::Helpers::BaseHelper
Defined in:
lib/yard/cli/stats.rb

Overview

Since:

Constant Summary

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]

Instance Attribute Summary (collapse)

Attributes included from Templates::Helpers::BaseHelper

#object, #owner, #serializer

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

Constructor Details

- (Stats) initialize(parse = true)

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

- (Array<String>) apis Originally defined in class Yardoc

Keep track of which APIs are to be shown

Returns:

Since:

  • 0.8.1

- (Array<String>) assets Originally defined in class Yardoc

Returns a list of assets to copy after generation

Returns:

  • (Array<String>)

    a list of assets to copy after generation

Since:

  • 0.6.0

- (Array<String>) excluded Originally defined in class Yardoc

Returns list of excluded paths (regexp matches)

Returns:

  • (Array<String>)

    list of excluded paths (regexp matches)

Since:

  • 0.5.3

- (Array<String>) files Originally defined in class Yardoc

Returns list of Ruby source files to process

Returns:

  • (Array<String>)

    list of Ruby source files to process

Since:

  • 0.2.1

- (Boolean) generate Originally defined in class Yardoc

Returns whether to generate output

Returns:

  • (Boolean)

    whether to generate output

Since:

  • 0.2.1

- (Boolean) has_markup Originally defined in class Yardoc

Returns whether markup option was specified

Returns:

  • (Boolean)

    whether markup option was specified

Since:

  • 0.7.0

- (Array<String>) hidden_apis Originally defined in class Yardoc

Keep track of which APIs are to be hidden

Returns:

Since:

  • 0.8.7

- (Array<Symbol>) hidden_tags Originally defined in class Yardoc

Returns a list of tags to hide from templates

Returns:

  • (Array<Symbol>)

    a list of tags to hide from templates

Since:

  • 0.6.0

- (Boolean) list Originally defined in class Yardoc

Returns whether to print a list of objects

Returns:

  • (Boolean)

    whether to print a list of objects

Since:

  • 0.5.5

- (Hash) options (readonly) Originally defined in class Yardoc

Returns the hash of options passed to the template.

Returns:

  • (Hash)

    the hash of options passed to the template.

See Also:

  • Templates::Engine#render

Since:

  • 0.2.1

- (String) options_file Originally defined in class YardoptsCommand

The options file name (defaults to DEFAULT_YARDOPTS_FILE)

Returns:

  • (String)

    the filename to load extra options from

Since:

  • 0.8.3

- (Boolean) parse

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

- (Boolean) save_yardoc Originally defined in class Yardoc

Returns whether objects should be serialized to .yardoc db

Returns:

  • (Boolean)

    whether objects should be serialized to .yardoc db

Since:

  • 0.2.1

- (Boolean) statistics Originally defined in class Yardoc

Returns whether to print statistics after parsing

Returns:

  • (Boolean)

    whether to print statistics after parsing

Since:

  • 0.6.0

- (Boolean) use_cache Originally defined in class Yardoc

Returns whether to use the existing yardoc db if the .yardoc already exists. Also makes use of file checksums to parse only changed files.

Returns:

  • (Boolean)

    whether to use the existing yardoc db if the .yardoc already exists. Also makes use of file checksums to parse only changed files.

Since:

  • 0.2.1

- (Boolean) use_document_file Originally defined in class YardoptsCommand

Returns whether to parse options from .document

Returns:

  • (Boolean)

    whether to parse options from .document

Since:

  • 0.8.3

- (Boolean) use_yardopts_file Originally defined in class YardoptsCommand

Returns whether to parse options from .yardopts

Returns:

  • (Boolean)

    whether to parse options from .yardopts

Since:

  • 0.8.3

- (Array<Symbol>) visibilities Originally defined in class Yardoc

Keep track of which visibilities are to be shown

Returns:

  • (Array<Symbol>)

    a list of visibilities

Since:

  • 0.5.6

Instance Method Details

- (Array<CodeObjects::Base>) all_objects

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



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

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

- (Object) description

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

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

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



146
147
148
149
150
151
152
153
154
155
# File 'lib/yard/cli/stats.rb', line 146

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
  log.puts("%-12s %s" % [name + ":", data])
end

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



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
# File 'lib/yard/cli/stats.rb', line 51

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) }

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

Prints list of undocumented objects

Since:

  • 0.6.0



74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
# File 'lib/yard/cli/stats.rb', line 74

def print_undocumented_objects
  return if !@undoc_list || @undoc_list.empty?
  log.puts
  log.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|
      log.puts("%-#{max}s     (%s)" % [object.path,
        [object.file, 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})"
      end
      log.puts object.path
      last_file = object.file
    end
  end
end

- (void) run(*args)

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
# File 'lib/yard/cli/stats.rb', line 33

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
end

- (Object) stats_for_classes

Statistics for classes

Since:

  • 0.6.0



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

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

- (Object) stats_for_constants

Statistics for constants

Since:

  • 0.6.0



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

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

- (Object) stats_for_files

Statistics for files

Since:

  • 0.6.0



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

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

- (Object) stats_for_methods

Statistics for methods

Since:

  • 0.6.0



129
130
131
132
133
134
135
# File 'lib/yard/cli/stats.rb', line 129

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

- (Object) stats_for_modules

Statistics for modules

Since:

  • 0.6.0



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

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