Class: JsDuck::Logger

Inherits:
Object
  • Object
show all
Includes:
Util::Singleton
Defined in:
lib/jsduck/logger.rb

Overview

Central logging of JsDuck

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Util::Singleton

included

Constructor Details

#initialize ⇒ Logger

Returns a new instance of Logger.



17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/jsduck/logger.rb', line 17

def initialize
  @verbose = false
  @colors = nil

  @warning_docs = [
    [:global, "Member doesn't belong to any class"],
    [:inheritdoc, "@inheritdoc referring to unknown class or member"],
    [:extend, "@extend/mixin/requires/uses referring to unknown class"],
    [:tag, "Use of unsupported @tag"],
    [:link, "{@link} to unknown class or member"],
    [:link_ambiguous, "{@link} is ambiguous"],
    [:link_auto, "Auto-detected link to unknown class or member"],
    [:html, "Unclosed HTML tag."],

    [:alt_name, "Name used as both classname and alternate classname"],
    [:name_missing, "Member or parameter has no name"],
    [:no_doc, "Member or class without documentation"],
    [:dup_param, "Method has two parameters with the same name"],
    [:dup_member, "Class has two members with the same name"],
    [:req_after_opt, "Required parameter comes after optional"],
    [:subproperty, "@param foo.bar where foo param doesn't exist"],
    [:sing_static, "Singleton class member marked as @static"],
    [:type_syntax, "Syntax error in {type definition}"],
    [:type_name, "Unknown type referenced in {type definition}"],
    [:enum, "Enum defined without any values in it"],

    [:image, "{@img} referring to missing file"],
    [:image_unused, "An image exists in --images dir that's not used"],
    [:cat_old_format, "Categories file uses old deprecated format"],
    [:cat_no_match, "Class pattern in categories file matches nothing"],
    [:cat_class_missing, "Class is missing from categories file"],
    [:guide, "Guide is missing from --guides dir"],

    [:aside, "Problem with @aside tag"],
    [:hide, "Problem with @hide tag"],
  ]
  # Turn off all warnings by default.
  # This is good for testing.
  # When running JSDuck app, the Options class enables most warnings.
  @warnings = {}
  @warning_docs.each do |w|
    @warnings[w[0]] = false
  end

  @shown_warnings = {}
end

Instance Attribute Details

#colors ⇒ Object

Set true to force colored output. Set false to force no colors.



15
16
17
 
# File 'lib/jsduck/logger.rb', line 15

def colors
  @colors
end

#verbose ⇒ Object

Set to true to enable verbose logging



11
12
13
 
# File 'lib/jsduck/logger.rb', line 11

def verbose
  @verbose
end

Instance Method Details

#doc_warnings ⇒ Object

get documentation for all warnings



86
87
88
 
# File 'lib/jsduck/logger.rb', line 86

def doc_warnings
  @warning_docs.map {|w| " #{@warnings[w[0]] ? '+' : '-'}#{w[0]} - #{w[1]}" }
end

#fatal(msg) ⇒ Object

Prints fatal error message with backtrace. The error param should be $! from resque block.



130
131
132
 
# File 'lib/jsduck/logger.rb', line 130

def fatal(msg)
  $stderr.puts paint(:red, "Error: ") + msg
end

#fatal_backtrace(msg, error) ⇒ Object

Prints fatal error message with backtrace. The error param should be $! from resque block.



136
137
138
139
140
141
 
# File 'lib/jsduck/logger.rb', line 136

def fatal_backtrace(msg, error)
  $stderr.puts paint(:red, "Error: ") + "#{msg}: #{error}"
  $stderr.puts
  $stderr.puts "Here's a full backtrace:"
  $stderr.puts error.backtrace
end

#format(filename = nil, line = nil) ⇒ Object

Formats filename and line number for output



117
118
119
120
121
122
123
124
125
126
 
# File 'lib/jsduck/logger.rb', line 117

def format(filename=nil, line=nil)
  out = ""
  if filename
    out = Util::OS.windows? ? filename.gsub('/', '\\') : filename
    if line
      out += ":#{line}:"
    end
  end
  paint(:magenta, out)
end

#log(msg, filename = nil) ⇒ Object

Prints log message with optional filename appended



65
66
67
68
69
 
# File 'lib/jsduck/logger.rb', line 65

def log(msg, filename=nil)
  if @verbose
    $stderr.puts paint(:green, msg) + " " + format(filename) + " ..."
  end
end

#set_warning(type, enabled) ⇒ Object

Enabled or disables a particular warning or all warnings when type == :all



73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/jsduck/logger.rb', line 73

def set_warning(type, enabled)
  if type == :all
    @warnings.each_key do |key|
      @warnings[key] = enabled
    end
  elsif @warnings.has_key?(type)
    @warnings[type] = enabled
  else
    warn(nil, "Warning of type '#{type}' doesn't exist")
  end
end

#warn(type, msg, filename = nil, line = nil) ⇒ Object

Prints warning message.

The type must be one of predefined warning types which can be toggled on/off with command-line options, or it can be nil, in which case the warning is always shown.

Ignores duplicate warnings - only prints the first one. Works best when –processes=0, but it reduces the amount of warnings greatly also when run multiple processes.

Optionally filename and line number will be inserted to message.



101
102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/jsduck/logger.rb', line 101

def warn(type, msg, filename=nil, line=nil)
  msg = paint(:yellow, "Warning: ") + format(filename, line) + " " + msg

  if type == nil || @warnings[type]
    if !@shown_warnings[msg]
      $stderr.puts msg
      @shown_warnings[msg] = true
    end
  elsif !@warnings.has_key?(type)
    warn(nil, "Unknown warning type #{type}")
  end

  return false
end

#warnings_logged? ⇒ Boolean

True when at least one warning was logged.

Returns:

  • (Boolean) 


144
145
146
 
# File 'lib/jsduck/logger.rb', line 144

def warnings_logged?
  @shown_warnings.length > 0
end