jsduck 5.1.0 → 5.2.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    YTQ4ZGE0ZGEzMTQxNDY1ZjhiY2FhNTliMmJjNTQ0OGY2NTZkY2VhMA==
+  data.tar.gz: !binary |-
+    ZWEzMjZmMGEzOTBmOGM4OGQ4NzZiY2NhMjA5OTZkZGVlMzdhMTc4NQ==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    ZjA3N2ZjODkwZjNhNjBiNWExNTNlZjI0YzA4Y2EyZmZjZDk5MWUyMzY1Y2Iy
+    NTlmYWY0MjJlODhjZjgwZGE3ZmY2YzZjZWI3MWE5OWVhM2ZjN2Q3YWJlODQy
+    Zjg0OGM1NDZmNTdkNDExNmJlN2ZmZTU4ODkxYWI1YTM3MWFhMjk=
+  data.tar.gz: !binary |-
+    NTc0ZDQ1NDMxYTU5MDhiMTYyMTFlN2RiODNlYTczYThkZjUzMDFkNzk4NTU3
+    NzY5YzVkNDMyYzA0NWI1MjM5NWQ4M2VkYzI2ZDcxNzQ0MGI0Y2Y5OWVkNDYz
+    MjE0MjFiZjRjNWIxNWYzMjcxMWU2YjNkMjY3M2VmNTZmMzg2ODY=

data/lib/jsduck/batch_processor.rb

@@ -14,6 +14,7 @@ require 'jsduck/process/versions'
 require 'jsduck/process/return_values'
 require 'jsduck/process/fires'
 require 'jsduck/process/lint'
+require 'jsduck/process/no_doc'
 require 'jsduck/process/circular_deps'
 
 module JsDuck
@@ -71,6 +72,7 @@ module JsDuck
       Process::ReturnValues.new(relations).process_all!
       Process::Fires.new(relations).process_all!
       Process::Lint.new(relations).process_all!
+      Process::NoDoc.new(relations).process_all!
       relations
     end
 

data/lib/jsduck/logger.rb

@@ -1,5 +1,7 @@
 require 'jsduck/util/singleton'
 require 'jsduck/util/os'
+require 'jsduck/warning/registry'
+require 'jsduck/warning/warn_exception'
 
 module JsDuck
 
@@ -18,51 +20,7 @@ module JsDuck
       @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"],
-        [: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"],
-        [: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"],
-        [: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"],
-      ]
-      # 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]] = {:enabled => false, :patterns => []}
-      end
+      @warnings = Warning::Registry.new
 
       @shown_warnings = {}
     end
@@ -77,31 +35,17 @@ 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)
-      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_warning(key, enabled, pattern) unless pattern && @warnings[key][:enabled] == enabled
-        end
-      elsif @warnings.has_key?(type)
-        if pattern
-          if @warnings[type][:enabled] == enabled
-            warn(nil, "Warning rule '#{enabled ? '+' : '-'}#{type}:#{pattern}' has no effect")
-          else
-            @warnings[type][:patterns] << Regexp.new(Regexp.escape(pattern))
-          end
-        else
-          @warnings[type] = {:enabled => enabled, :patterns => []}
-        end
-      else
-        warn(nil, "Warning of type '#{type}' doesn't exist")
+    def set_warning(type, enabled, pattern=nil, params=[])
+      begin
+        @warnings.set(type, enabled, pattern, params)
+      rescue Warning::WarnException => e
+        warn(nil, e.message)
       end
     end
 
     # get documentation for all warnings
     def doc_warnings
-      @warning_docs.map {|w| " #{@warnings[w[0]][:enabled] ? '+' : '-'}#{w[0]} - #{w[1]}" }
+      @warnings.doc
     end
 
     # Prints warning message.
@@ -125,46 +69,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
 
-    # True when the warning is enabled for the given type and filename
-    # combination.
-    def warning_enabled?(type, filename)
-      if type == nil
-        true
-      elsif !@warnings.has_key?(type)
-        warn(nil, "Unknown warning type #{type}")
-        false
-      else
-        rule = @warnings[type]
-        if rule[:patterns].any? {|re| filename =~ re }
-          !rule[:enabled]
-        else
-          rule[:enabled]
-        end
-      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
+    # 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]
+
+      if @warnings.enabled?(:nodoc, filename, [type, visibility])
+        print_warning(msg, filename, line)
       end
-      paint(:magenta, out)
     end
 
     # Prints fatal error message with backtrace.
@@ -202,6 +124,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

data/lib/jsduck/news.rb

@@ -27,7 +27,7 @@ module JsDuck
         "<div id='news-content' style='#{style}'>",
           "<div class='section'>",
             "<h1>New in this version</h1>",
-            render_columns(@new_items),
+              render_news(@new_items),
             "<div style='clear:both'></div>",
           "</div>",
         "</div>",
@@ -91,6 +91,14 @@ module JsDuck
       str[0,1].upcase + str[1..-1]
     end
 
+    def render_news(new_items)
+      if new_items.length > 0
+        render_columns(new_items)
+      else
+        "<h3>Nothing new.</h3>"
+      end
+    end
+
     def render_columns(new_items)
       align = ["left-column", "middle-column", "right-column"]
       i = -1

data/lib/jsduck/options.rb

@@ -6,6 +6,7 @@ require 'jsduck/util/io'
 require 'jsduck/util/parallel'
 require 'jsduck/tag_registry'
 require 'jsduck/js/ext_patterns'
+require 'jsduck/warning/parser'
 
 module JsDuck
 
@@ -98,7 +99,7 @@ module JsDuck
       ]
       @ext4_events = nil
 
-      @version = "5.1.0"
+      @version = "5.2.0"
       # Customizing output
       @title = "Documentation - JSDuck"
       @header = "<strong>Documentation</strong> JSDuck"
@@ -148,7 +149,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
@@ -672,7 +673,7 @@ module JsDuck
           Logger.verbose = true
         end
 
-        opts.on('--warnings=+A,-B,+C', Array,
+        opts.on('--warnings=+A,-B,+C',
           "Turns warnings selectively on/off.",
           "",
           " +all - to turn on all warnings.",
@@ -696,13 +697,12 @@ module JsDuck
           "(Those with '+' in front of them default to on)",
           "",
           *Logger.doc_warnings) do |warnings|
-          warnings.each do |op|
-            if op =~ /^([-+]?)(\w+)(?::(.*))?$/
-              enable = !($1 == "-")
-              name = $2.to_sym
-              path = $3
-              Logger.set_warning(name, enable, path)
+          begin
+            Warning::Parser.new(warnings).parse.each do |w|
+              Logger.set_warning(w[:type], w[:enabled], w[:path], w[:params])
             end
+          rescue Warning::WarnException => e
+            Logger.warn(nil, e.message)
           end
         end
 

data/lib/jsduck/process/accessors.rb

@@ -92,7 +92,7 @@ module JsDuck
             :params => [{
                 :type => cfg[:type],
                 :name => cfg[:name],
-                :doc => "",
+                :doc => "The new value.",
               }],
             :id => "method-" + name,
           }, cfg)

data/lib/jsduck/process/lint.rb

@@ -1,5 +1,4 @@
 require 'jsduck/logger'
-require 'jsduck/class'
 
 module JsDuck
   module Process
@@ -14,7 +13,6 @@ module JsDuck
 
       # Runs the linter
       def process_all!
-        warn_no_doc
         warn_unnamed
         warn_optional_params
         warn_duplicate_params
@@ -37,32 +35,6 @@ module JsDuck
         end
       end
 
-      # print warning for each class or public member with no name
-      def warn_no_doc
-        @relations.each do |cls|
-
-          if cls[:doc] == "" && !cls[:private]
-            warn(:no_doc, "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[:doc] == ""
-                warn(:no_doc_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)
-                end
-              end
-
-            end
-          end
-
-        end
-      end
-
       # print warning for each non-optional parameter that follows an optional parameter
       def warn_optional_params
         each_member do |member|

data/lib/jsduck/process/no_doc.rb

@@ -0,0 +1,50 @@
+require 'jsduck/logger'
+require 'jsduck/class'
+
+module JsDuck
+  module Process
+
+    # Reports missing documentation
+    class NoDoc
+      def initialize(relations)
+        @relations = relations
+      end
+
+      # Prints warning for each class or public member with no name
+      def process_all!
+        @relations.each do |cls|
+
+          if cls[:doc] == ""
+            warn(:class, "No documentation for #{cls[:name]}", cls)
+          end
+
+          cls.all_local_members.each do |member|
+            if !member[:hide] && !JsDuck::Class.constructor?(member)
+              if member[:doc] == ""
+                warn(:member, "No documentation for #{member[:owner]}##{member[:name]}", member)
+              end
+
+              (member[:params] || []).each do |p|
+                if p[:doc] == ""
+                  warn(:param, "No documentation for parameter #{p[:name]} of #{member[:owner]}##{member[:name]}", member)
+                end
+              end
+
+            end
+          end
+
+        end
+      end
+
+      private
+
+      def warn(type, msg, owner)
+        visibility = owner[:private] ? :private : (owner[:protected] ? :protected : :public)
+
+        Logger.warn_nodoc(type, visibility, msg, owner[:files][0])
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/tag/fires.rb

@@ -42,6 +42,8 @@ module JsDuck::Tag
     end
 
     def to_html(m)
+      return unless m[:fires] && m[:fires].length > 0
+
       return [
         "<h3 class='pa'>Fires</h3>",
         "<ul>",

data/lib/jsduck/util/io.rb

@@ -25,7 +25,17 @@ module JsDuck
 
       # Reads given filename into string
       def self.read(filename)
-        File.open(filename, "r:"+@@encoding) {|f| f.read }
+        File.open(filename, "r:"+@@encoding) {|f| self.strip_utf8_bom(f.read) }
+      end
+
+      # Takes care of removing UTF-8 byte order mark in Ruby <= 1.8 which
+      # doesn't have built-in encodings support.
+      def self.strip_utf8_bom(string)
+        if "".respond_to?(:encoding)
+          string
+        else
+          string.sub(/\A\xEF\xBB\xBF/, "")
+        end
       end
 
     end

data/lib/jsduck/warning/all.rb

@@ -0,0 +1,36 @@
+module JsDuck
+  module Warning
+
+    # A composite warning, encompassing all the other warning types.
+    class All
+
+      # Creates a deprecated warning with a mapping to :nodoc warning
+      # type with given parameters.  The warning is disabled by
+      # default.
+      def initialize(warnings)
+        @warnings = warnings
+      end
+
+      # Enables/disables all warnings.
+      def set(enabled, path_pattern=nil, params=[])
+        # When used with a path_pattern, only add the pattern to the rules
+        # where it can have an effect - otherwise we get a warning.
+        @warnings.each do |w|
+          w.set(enabled, path_pattern, params) unless path_pattern && w.enabled? == enabled
+        end
+      end
+
+      # Doesn't make sense to check if the :all warning is enabled.
+      def enabled?(filename="", params=[])
+        raise "Warning type 'all' must not be checked for enabled/disabled"
+      end
+
+      # The all-warning is documented separately
+      def doc
+        nil
+      end
+
+    end
+
+  end
+end