New nodoc warning to replace no_doc* warnings. (28924047) · Commits · extjs / jsduck

lib/jsduck/logger.rb

+44 −27

Original line number	Diff line number	Diff line
		@@ -34,9 +34,9 @@ module JsDuck
		# Enables or disables a particular warning
		# or all warnings when type == :all.
		# Additionally a filename pattern can be specified.
		def set_warning(type, enabled, pattern=nil)
		def set_warning(type, enabled, pattern=nil, params=[])
		begin
		@warnings.set(type, enabled, pattern)
		@warnings.set(type, enabled, pattern, params)
		rescue Exception => e
		warn(nil, e.message)
		end
		@@ -68,38 +68,24 @@ module JsDuck
		filename = filename[:filename]
		end

		msg = paint(:yellow, "Warning: ") + format(filename, line) + " " + msg

		if warning_enabled?(type, filename)
		if !@shown_warnings[msg]
		$stderr.puts msg
		@shown_warnings[msg] = true
		end
		print_warning(msg, filename, line)
		end

		return false
		end

		def warning_enabled?(type, filename)
		if type == nil
		true
		elsif !@warnings.has?(type)
		warn(nil, "Unknown warning type #{type}")
		else
		@warnings.enabled?(type, filename)
		end
		end
		# Prints :nodoc warning message.
		#
		# Because the :nodoc warning needs different parameters, for now
		# we're using a separate method specially for these.
		def warn_nodoc(type, visibility, msg, file)
		filename = file[:filename]
		line = file[:linenr]

		# Formats filename and line number for output
		def format(filename=nil, line=nil)
		out = ""
		if filename
		out = Util::OS.windows? ? filename.gsub('/', '\\') : filename
		if line
		out += ":#{line}:"
		end
		if @warnings.enabled?(:nodoc, filename, [type, visibility])
		print_warning(msg, filename, line)
		end
		paint(:magenta, out)
		end

		# Prints fatal error message with backtrace.
		@@ -137,6 +123,37 @@ module JsDuck

		CLEAR = "\e[0m"

		def warning_enabled?(type, filename)
		if type == nil
		true
		elsif !@warnings.has?(type)
		warn(nil, "Unknown warning type #{type}")
		else
		@warnings.enabled?(type, filename)
		end
		end

		def print_warning(msg, filename, line)
		warning = paint(:yellow, "Warning: ") + format(filename, line) + " " + msg

		if !@shown_warnings[warning]
		$stderr.puts warning
		@shown_warnings[warning] = true
		end
		end

		# Formats filename and line number for output
		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

		# Helper for doing colored output in UNIX terminal
		#
		# Only does color output when STDERR is attached to TTY

lib/jsduck/no_doc_warning.rb

0 → 100644

+46 −0

Original line number	Diff line number	Diff line
		require 'set'

		module JsDuck

		# Missing documentation warnings management
		class NoDocWarning

		TYPES = Set[nil, :class, :member, :param]
		VISIBILITIES = Set[nil, :public, :protected, :private]

		def initialize
		@rules = []
		# disable by default
		set(false)
		end

		# Enables or disables a particular sub-warning
		def set(enabled, type=nil, visibility=nil, path_pattern=nil)
		unless TYPES.include?(type) && VISIBILITIES.include?(visibility)
		raise "Invalid warning parameters: nodoc(#{type},#{visibility})"
		end

		@rules << {
		:enabled => enabled,
		:type => type,
		:visibility => visibility,
		:path_re => path_pattern ? Regexp.new(Regexp.escape(path_pattern)) : nil
		}
		end

		# True when the warning is enabled for the given
		# type/visibility/filename combination.
		def enabled?(type, visibility, filename)
		# Filter out rules that apply to our current item
		matches = @rules.find_all do \|r\|
		(r[:type].nil? \|\| r[:type] == type) &&
		(r[:visibility].nil? \|\| r[:visibility] == visibility) &&
		(r[:path_re].nil? \|\| r[:path_re] =~ filename)
		end

		return matches.last[:enabled]
		end

		end

		end

lib/jsduck/options.rb

+6 −4

Original line number	Diff line number	Diff line
		@@ -148,7 +148,7 @@ module JsDuck
		Logger.set_warning(:link_auto, false)
		Logger.set_warning(:param_count, false)
		Logger.set_warning(:fires, false)
		Logger.set_warning(:no_doc_param, false)
		Logger.set_warning(:nodoc, false)

		@optparser = create_option_parser
		end
		@@ -697,11 +697,13 @@ module JsDuck
		"",
		*Logger.doc_warnings) do \|warnings\|
		warnings.each do \|op\|
		if op =~ /^([-+]?)(\w+)(?::(.*))?$/
		# XXX: Can't rely any more on the Array type of OptionParser
		if op =~ /^([-+]?)(\w+)(?:$([^)])$)?(?::(.))?$/
		enable = !($1 == "-")
		name = $2.to_sym
		path = $3
		Logger.set_warning(name, enable, path)
		params = ($3 \|\| "").split(/,/).map {\|p\| p.strip }.map {\|p\| (p == "") ? nil : p.to_sym }
		path = $4
		Logger.set_warning(name, enable, path, params)
		end
		end
		end

lib/jsduck/process/no_doc.rb

+9 −8

Original line number	Diff line number	Diff line
		@@ -14,19 +14,19 @@ module JsDuck
		def process_all!
		@relations.each do \|cls\|

		if cls[:doc] == "" && !cls[:private]
		warn(:no_doc, "No documentation for #{cls[:name]}", cls)
		if cls[:doc] == ""
		warn(:class, "No documentation for #{cls[:name]}", cls)
		end

		cls.all_local_members.each do \|member\|
		if !member[:private] && !member[:hide] && !JsDuck::Class.constructor?(member)
		if !member[:hide] && !JsDuck::Class.constructor?(member)
		if member[:doc] == ""
		warn(:no_doc_member, "No documentation for #{member[:owner]}##{member[:name]}", member)
		warn(:member, "No documentation for #{member[:owner]}##{member[:name]}", member)
		end

		(member[:params] \|\| []).each do \|p\|
		if p[:doc] == ""
		warn(:no_doc_param, "No documentation for parameter #{p[:name]} of #{member[:owner]}##{member[:name]}", member)
		warn(:param, "No documentation for parameter #{p[:name]} of #{member[:owner]}##{member[:name]}", member)
		end
		end

		@@ -38,9 +38,10 @@ module JsDuck

		private

		# Prints warning + filename and linenumber from doc-context
		def warn(type, msg, member)
		Logger.warn(type, msg, member[:files][0])
		def warn(type, msg, owner)
		visibility = owner[:private] ? :private : (owner[:protected] ? :protected : :public)

		Logger.warn_nodoc(type, visibility, msg, owner[:files][0])
		end

		end

lib/jsduck/warnings.rb

+24 −5

Original line number	Diff line number	Diff line
		require 'jsduck/no_doc_warning'

		module JsDuck

		# Warnings management
		@@ -18,9 +20,6 @@ module JsDuck

		[:alt_name, "Name used as both classname and alternate classname"],
		[:name_missing, "Member or parameter has no name"],
		[:no_doc, "Public class without documentation"],
		[:no_doc_member, "Public member without documentation"],
		[:no_doc_param, "Parameter of public member 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"],
		@@ -41,7 +40,18 @@ module JsDuck

		[:aside, "Problem with @aside tag"],
		[:hide, "Problem with @hide tag"],

		[:nodoc, "Missing documentation"],
		]

		@deprecated = {
		:no_doc => {:msg => "Alias for +nodoc(class,public)", :params => [:class, :public]},
		:no_doc_member => {:msg => "Alias for +nodoc(member,public)", :params => [:member, :public]},
		:no_doc_param => {:msg => "Alias for +nodoc(param,public)", :params => [:param, :public]},
		}

		@nodoc = NoDocWarning.new

		# Turn off all warnings by default.
		# This is good for testing.
		# When running JSDuck app, the Options class enables most warnings.
		@@ -54,13 +64,18 @@ module JsDuck
		# Enables or disables a particular warning
		# or all warnings when type == :all.
		# Additionally a filename pattern can be specified.
		def set(type, enabled, pattern=nil)
		def set(type, enabled, pattern=nil, params=[])
		if type == :all
		# When used with a pattern, only add the pattern to the rules
		# where it can have an effect - otherwise we get a warning.
		@warnings.each_key do \|key\|
		set(key, enabled, pattern) unless pattern && @warnings[key][:enabled] == enabled
		end
		elsif type == :nodoc
		@nodoc.set(enabled, params[0], params[1], pattern)
		elsif @deprecated[type]
		params = @deprecated[type][:params]
		@nodoc.set(enabled, params[0], params[1], pattern)
		elsif @warnings.has_key?(type)
		if pattern
		if @warnings[type][:enabled] == enabled
		@@ -83,7 +98,11 @@ module JsDuck

		# True when the warning is enabled for the given type and filename
		# combination.
		def enabled?(type, filename)
		def enabled?(type, filename, params=[])
		if type == :nodoc
		return @nodoc.enabled?(params[0], params[1], filename)
		end

		rule = @warnings[type]
		if rule[:patterns].any? {\|re\| filename =~ re }
		!rule[:enabled]