jsduck 5.1.0 → 5.2.0

data/lib/jsduck/warning/basic.rb

@@ -0,0 +1,51 @@
+require 'jsduck/warning/warn_exception'
+
+module JsDuck
+  module Warning
+
+    # A basic warning type.
+    class Basic
+
+      # Creates a simple warning with a message text.
+      # The warning is disabled by default.
+      def initialize(type, msg)
+        @type = type
+        @msg = msg
+        @enabled = false
+        @patterns = []
+      end
+
+      # Enables or disables the warning.
+      # Optionally enables/disables it for files matching a path_pattern.
+      def set(enabled, path_pattern=nil, params=[])
+        if path_pattern
+          if @enabled == enabled
+            raise WarnException, "Warning rule '#{enabled ? '+' : '-'}#{@type}:#{path_pattern}' has no effect"
+          else
+            @patterns << Regexp.new(Regexp.escape(path_pattern))
+          end
+        else
+          @enabled = enabled
+          @patterns = []
+        end
+      end
+
+      # True when warning is enabled for the given filename.
+      # (The params parameter is ignored).
+      def enabled?(filename="", params=[])
+        if @patterns.any? {|re| filename =~ re }
+          !@enabled
+        else
+          @enabled
+        end
+      end
+
+      # Documentation for the warning.
+      def doc
+        " #{@enabled ? '+' : '-'}#{@type} - #{@msg}"
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/warning/deprecated.rb

@@ -0,0 +1,40 @@
+require 'jsduck/warning/warn_exception'
+
+module JsDuck
+  module Warning
+
+    # A deprecated :no_doc* warning which maps to the new :nodoc
+    # warning.
+    class Deprecated
+
+      # Creates a deprecated warning with a mapping to :nodoc warning
+      # type with given parameters.  The warning is disabled by
+      # default.
+      def initialize(type, msg, nodoc, params)
+        @type = type
+        @msg = msg
+        @enabled = false
+        @nodoc = nodoc
+        @params = params
+      end
+
+      # Enables or disables the mapped :nodoc warning.
+      def set(enabled, path_pattern=nil, params=[])
+        @nodoc.set(enabled, path_pattern, @params)
+        raise WarnException, "Warning type #{@type} is deprecated, use nodoc(#{@params.join(',')}) instead"
+      end
+
+      # This method shouldn't be called.
+      def enabled?(filename="", params=[])
+        raise "Deprecated warning '#{@type}' must not be checked for enabled/disabled"
+      end
+
+      # Documentation for the warning.
+      def doc
+        " -#{@type} - #{@msg} DEPRECATED"
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/warning/nodoc.rb

@@ -0,0 +1,79 @@
+require 'jsduck/warning/warn_exception'
+require 'set'
+
+module JsDuck
+  module Warning
+
+    # Missing documentation warning.
+    class Nodoc
+
+      TYPES = Set[nil, :class, :member, :param]
+      VISIBILITIES = Set[nil, :public, :protected, :private]
+
+      # Creates the :nodoc warning type
+      def initialize
+        @rules = []
+        # disable by default
+        set(false)
+      end
+
+      # Enables or disables a particular sub-warning
+      def set(enabled, path_pattern=nil, params=[])
+        type = params[0]
+        visibility = params[1]
+
+        unless TYPES.include?(type) && VISIBILITIES.include?(visibility)
+          raise WarnException, "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 filename and
+      # params combination, where the params contain type and
+      # visibility setting.
+      def enabled?(filename="", params=[])
+        type = params[0]
+        visibility = params[1]
+
+        # 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
+
+      # Extensive documentation for :nodoc warning
+      def doc
+        [
+          "",
+          " -nodoc(<type>,<visibility>) - Missing documentation",
+          "",
+          "     This warning can take parameters with the following values:",
+          "",
+          "     <type> = class | member | param",
+          "     <visibility> = public | protected | private",
+          "",
+          "     So, to report missing documentation of public classes:",
+          "",
+          "         --warnings='+nodoc(class,public)'",
+          "",
+          "     Or, to report missing docs of all protected items in /etc:",
+          "",
+          "         --warnings='+nodoc(,protected):/etc/'",
+          "",
+        ]
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/warning/parser.rb

@@ -0,0 +1,168 @@
+require 'strscan'
+require 'jsduck/warning/warn_exception'
+
+module JsDuck
+  module Warning
+
+    # Parses the warnings passed in from command line
+    #
+    # Grammar:
+    #
+    # <warnings>     := <warning> [ "," <warning> ]*
+    #
+    # <warning>      := ["+" | "-"] <type> [<params-block>] [<path-block>]
+    #
+    # <type>         := \w+
+    #
+    # <params-block> := "(" [<params>] ")"
+    #
+    # <params>       := <param> [ "," <param> ]*
+    #
+    # <param>        := \w+ | ""
+    #
+    # <path-block>   := ":" <path>
+    #
+    # <path>         := .*
+    #
+    class Parser
+      def initialize(string)
+        @scanner = StringScanner.new(string)
+      end
+
+      # Parses the warnings string.
+      #
+      # For example the following string:
+      #
+      #     +tag,-nodoc(class,private):/some/path
+      #
+      # is parsed into the following structure:
+      #
+      #     [
+      #       {
+      #         :type => :tag,
+      #         :enabled => true,
+      #         :params => [],
+      #         :path => nil,
+      #       },
+      #       {
+      #         :type => :nodoc,
+      #         :enabled => false,
+      #         :params => [:class, :private],
+      #         :path => "/some/path",
+      #       },
+      #     ]
+      #
+      # When scanning fails, raises an exception with a descriptive
+      # message.
+      def parse
+        results = []
+
+        while !eos?
+          results << warning
+          match(/,/)
+        end
+
+        results
+      end
+
+      private
+
+      def warning
+        return {
+          :enabled => enabled,
+          :type => type,
+          :params => params,
+          :path => path,
+        }
+      end
+
+      def enabled
+        if match(/\+/)
+          true
+        elsif match(/-/)
+          false
+        else
+          true
+        end
+      end
+
+      def type
+        require(/\w+/).to_sym
+      end
+
+      def params
+        if match(/\(/)
+          ps = []
+
+          while !look(/\)/)
+            ps << param
+            break unless match(/,/)
+          end
+
+          require(/\)/)
+
+          ps
+        else
+          []
+        end
+      end
+
+      def param
+        if p = match(/\w+/)
+          p.to_sym
+        elsif look(/,/)
+          nil
+        else
+          unexpected_char
+        end
+      end
+
+      def path
+        if match(/:/)
+          match(/[^,]*/).strip
+        else
+          nil
+        end
+      end
+
+      # scans a pattern, throws error on failure
+      def require(re)
+        if m = match(re)
+          m
+        else
+          unexpected_char
+        end
+      end
+
+      # Reports unexpected character
+      def unexpected_char
+        # do successful empty scan, so we can use #pre_match and #post_match
+        @scanner.scan(//)
+        raise WarnException, "Unexpected '#{@scanner.peek(1)}' at " +
+          "--warnings='#{@scanner.pre_match}<HERE>#{@scanner.post_match}'"
+      end
+
+      # scans a pattern, ignoring the optional whitespace before it
+      def match(re)
+        skip_ws
+        @scanner.scan(re)
+      end
+
+      def look(re)
+        skip_ws
+        @scanner.check(re)
+      end
+
+      def eos?
+        skip_ws
+        @scanner.eos?
+      end
+
+      def skip_ws
+        @scanner.scan(/\s*/)
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/warning/registry.rb

@@ -0,0 +1,106 @@
+require 'jsduck/warning/basic'
+require 'jsduck/warning/nodoc'
+require 'jsduck/warning/deprecated'
+require 'jsduck/warning/all'
+require 'jsduck/warning/warn_exception'
+
+module JsDuck
+  module Warning
+
+    # Warnings management
+    class Registry
+
+      def initialize
+        @warnings = []
+        @warnings_map = {}
+
+        # Basic warnings
+        [
+          [: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"],
+          [:tag_repeated, "An @tag used multiple times, but only once allowed"],
+          [:tag_syntax, "@tag syntax error"],
+          [: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"],
+          [: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"],
+          [:param_count, "Less parameters documented than detected from code"],
+          [: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 with invalid values or no values at all"],
+          [:fires, "@fires references unknown event"],
+
+          [: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"],
+        ].each do |w|
+          register(w[0], Warning::Basic.new(w[0], w[1]))
+        end
+
+        # :nodoc warning
+        register(:nodoc, Warning::Nodoc.new)
+
+        # :all warning (encompasses all other warning types)
+        register(:all, Warning::All.new(@warnings.clone))
+
+        # :deprecated warnings (linking to :nodoc warning)
+        [
+          {:type => :no_doc, :msg => "Alias for nodoc(class,public)", :params => [:class, :public]},
+          {:type => :no_doc_member, :msg => "Alias for nodoc(member,public)", :params => [:member, :public]},
+          {:type => :no_doc_param, :msg => "Alias for nodoc(param,public)", :params => [:param, :public]},
+        ].each do |w|
+          register(w[:type], Warning::Deprecated.new(w[:type], w[:msg], @warnings_map[:nodoc], w[:params]))
+        end
+
+      end
+
+      def register(type, warning)
+        @warnings << warning
+        @warnings_map[type] = warning
+      end
+
+      # Enables or disables a particular warning type.
+      # Additionally a filename pattern and params for the warning can be specified.
+      def set(type, enabled, path_pattern=nil, params=[])
+        if @warnings_map[type]
+          @warnings_map[type].set(enabled, path_pattern, params)
+        else
+          raise WarnException, "Warning of type '#{type}' doesn't exist"
+        end
+      end
+
+      # get documentation for all warnings
+      def doc
+        @warnings.map {|w| w.doc }.compact.flatten
+      end
+
+      # True when the warning is enabled for the given type and
+      # filename combination.
+      def enabled?(type, filename, params=[])
+        @warnings_map[type].enabled?(filename, params)
+      end
+
+      def has?(type)
+        @warnings_map.has_key?(type)
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/warning/warn_exception.rb

@@ -0,0 +1,10 @@
+module JsDuck
+  module Warning
+
+    # An exception thrown by JsDuck::Warning classes that is supposed
+    # to result in a warning being logged by Logger.
+    class WarnException < Exception
+    end
+
+  end
+end