jsduck 4.0.1 → 4.1.1

data/lib/jsduck/lint.rb

@@ -17,6 +17,7 @@ module JsDuck
       warn_optional_params
       warn_duplicate_params
       warn_duplicate_members
+      warn_singleton_statics
       warn_empty_enums
     end
 
@@ -95,10 +96,21 @@ module JsDuck
       end
     end
 
+    # Print warnings for static members in singleton classes
+    def warn_singleton_statics
+      @relations.each do |cls|
+        if cls[:singleton]
+          cls.find_members({:local => true, :static => true}).each do |m|
+            warn(:sing_static, "Static members don't make sense in singleton class #{cls[:name]}", m)
+          end
+        end
+      end
+    end
+
     # print warnings for enums with no values
     def warn_empty_enums
       @relations.each do |cls|
-        if cls[:enum] && cls[:members][:property].length == 0
+        if cls[:enum] && cls[:members].length == 0
           warn(:enum, "Enum #{cls[:name]} defined without values in it", cls)
         end
       end
@@ -112,7 +124,7 @@ module JsDuck
     # Prints warning + filename and linenumber from doc-context
     def warn(type, msg, member)
       context = member[:files][0]
-      Logger.instance.warn(type, msg, context[:filename], context[:linenr])
+      Logger.warn(type, msg, context[:filename], context[:linenr])
     end
 
   end

data/lib/jsduck/logger.rb

@@ -1,11 +1,11 @@
-require 'singleton'
-require 'jsduck/os'
+require 'jsduck/util/singleton'
+require 'jsduck/util/os'
 
 module JsDuck
 
   # Central logging of JsDuck
   class Logger
-    include Singleton
+    include Util::Singleton
 
     # Set to true to enable verbose logging
     attr_accessor :verbose
@@ -25,7 +25,6 @@ module JsDuck
         [: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"],
-        [:dup_asset, "Duplicate guide/video/example"],
         [: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"],
@@ -110,7 +109,7 @@ module JsDuck
     def format(filename=nil, line=nil)
       out = ""
       if filename
-        out = OS::windows? ? filename.gsub('/', '\\') : filename
+        out = Util::OS.windows? ? filename.gsub('/', '\\') : filename
         if line
           out += ":#{line}:"
         end
@@ -153,7 +152,7 @@ module JsDuck
     # Only does color output when STDERR is attached to TTY
     # i.e. is not piped/redirected.
     def paint(color_name, msg)
-      if OS.windows? || !$stderr.tty?
+      if Util::OS.windows? || !$stderr.tty?
         msg
       else
         COLORS[color_name] + msg + CLEAR

data/lib/jsduck/members_index.rb

@@ -0,0 +1,132 @@
+require 'jsduck/logger'
+
+module JsDuck
+
+  # Helper for JsDuck::Class for indexing its members.
+  #
+  # While indexing the members of a class it accesses the MembersIndex
+  # instances of parent and mixins of that class through the
+  # #members_index accessor.  This isn't the nicest approach, but
+  # better than having all of this functionality inside the
+  # JsDuck::Class itself.
+  class MembersIndex
+    def initialize(cls)
+      @cls = cls
+      @map_by_id = nil
+      @global_map_by_id = nil
+      @global_map_by_name = nil
+    end
+
+    # Returns hash of all members by name (including inherited ones)
+    def global_by_name
+      unless @global_map_by_name
+        @global_map_by_name = {}
+
+        global_by_id.each_pair do |id, m|
+          @global_map_by_name[m[:name]] = [] unless @global_map_by_name[m[:name]]
+          @global_map_by_name[m[:name]] << m
+        end
+      end
+
+      @global_map_by_name
+    end
+
+    # Returns hash of all members by ID (including inherited ones)
+    def global_by_id
+      unless @global_map_by_id
+        # Make copy of parent class members.
+        # Otherwise we'll be merging directly into parent class.
+        @global_map_by_id = @cls.parent ? @cls.parent.members_index.global_by_id.clone : {}
+
+        @cls.mixins.each do |mix|
+          merge!(@global_map_by_id, mix.members_index.global_by_id)
+        end
+
+        # Exclude all non-inheritable static members
+        @global_map_by_id.delete_if {|id, m| m[:meta][:static] && !m[:inheritable] }
+
+        merge!(@global_map_by_id, local_by_id)
+      end
+
+      @global_map_by_id
+    end
+
+    # Returns hash of local members by ID (no inherited members)
+    def local_by_id
+      unless @map_by_id
+        @map_by_id = {}
+
+        @cls[:members].each do |m|
+          @map_by_id[m[:id]] = m
+        end
+      end
+
+      @map_by_id
+    end
+
+    # Clears the search cache.
+    # Using this is REALLY BAD - try to get rid of it.
+    def invalidate!
+      @map_by_id = nil
+      @global_map_by_id = nil
+      @global_map_by_name = nil
+
+      @cls.parent.members_index.invalidate! if @cls.parent
+
+      @cls.mixins.each {|mix| mix.members_index.invalidate! }
+    end
+
+    private
+
+    # merges second members hash into first one
+    def merge!(hash1, hash2)
+      hash2.each_pair do |name, m|
+        if m[:meta] && m[:meta][:hide]
+          if hash1[name]
+            hash1.delete(name)
+          else
+            ctx = m[:files][0]
+            msg = "@hide used but #{m[:tagname]} #{m[:name]} not found in parent class"
+            Logger.warn(:hide, msg, ctx[:filename], ctx[:linenr])
+          end
+        else
+          if hash1[name]
+            store_overrides(hash1[name], m)
+          end
+          hash1[name] = m
+        end
+      end
+    end
+
+    # Invoked when merge! finds two members with the same name.
+    # New member always overrides the old, but inside new we keep
+    # a list of members it overrides.  Normally one member will
+    # override one other member, but a member from mixin can override
+    # multiple members - although there's not a single such case in
+    # ExtJS, we have to handle it.
+    #
+    # Every overridden member is listed just once.
+    def store_overrides(old, new)
+      # Sometimes a class is included multiple times (like Ext.Base)
+      # resulting in its members overriding themselves.  Because of
+      # this, ignore overriding itself.
+      if new[:owner] != old[:owner]
+        new[:overrides] = [] unless new[:overrides]
+        unless new[:overrides].any? {|m| m[:owner] == old[:owner] }
+          # Make a copy of the important properties for us.  We can't
+          # just push the actual `old` member itself, because there
+          # can be circular overrides (notably with Ext.Base), which
+          # will result in infinite loop when we try to convert our
+          # class into JSON.
+          new[:overrides] << {
+            :name => old[:name],
+            :owner => old[:owner],
+            :id => old[:id],
+          }
+        end
+      end
+    end
+
+  end
+
+end

data/lib/jsduck/merger.rb

@@ -48,8 +48,7 @@ module JsDuck
       # Used by Aggregator to determine if we're dealing with Ext4 code
       h[:code_type] = code[:code_type] if code[:code_type]
 
-      h[:members] = Class.default_members_hash
-      h[:statics] = Class.default_members_hash
+      h[:members] = []
 
       h
     end
@@ -57,6 +56,7 @@ module JsDuck
     def merge_like_method(docs, code)
       h = do_merge(docs, code)
       h[:params] = merge_params(docs, code)
+      h[:meta][:chainable] = code[:chainable] if code[:chainable]
       h
     end
 
@@ -81,7 +81,7 @@ module JsDuck
       end
 
       h[:name] = merge_name(docs, code)
-      h[:id] = create_member_id(h)
+      h[:id] = JsDuck::Class.member_id(h)
 
       # Copy private to meta
       h[:meta][:private] = h[:private] if h[:private]
@@ -96,12 +96,6 @@ module JsDuck
       h
     end
 
-    def create_member_id(m)
-      # Sanitize $ in member names with something safer
-      name = m[:name].gsub(/\$/, 'S-')
-      "#{m[:meta][:static] ? 'static-' : ''}#{m[:tagname]}-#{name}"
-    end
-
     # Given array of full alias names like "foo.bar", "foo.baz"
     # build hash like {"foo" => ["bar", "baz"]}
     def build_aliases_hash(aliases)

data/lib/jsduck/options.rb

@@ -1,7 +1,9 @@
 require 'jsduck/option_parser'
 require 'jsduck/meta_tag_registry'
 require 'jsduck/logger'
-require 'jsduck/json_duck'
+require 'jsduck/util/json'
+require 'jsduck/util/os'
+require 'jsduck/util/parallel'
 
 module JsDuck
 
@@ -24,10 +26,8 @@ module JsDuck
     attr_accessor :guides
     attr_accessor :videos
     attr_accessor :examples
-    attr_accessor :stats
     attr_accessor :categories_path
     attr_accessor :source
-    attr_accessor :pretty_json
     attr_accessor :images
     attr_accessor :link_tpl
     attr_accessor :img_tpl
@@ -38,7 +38,6 @@ module JsDuck
     attr_accessor :tests
 
     # Debugging
-    attr_accessor :processes
     attr_accessor :template_dir
     attr_accessor :template_links
     attr_accessor :extjs_path
@@ -79,7 +78,7 @@ module JsDuck
       @ext4_events = nil
       @meta_tag_paths = []
 
-      @version = "4.0.1"
+      @version = "4.1.1"
 
       # Customizing output
       @title = "Documentation - JSDuck"
@@ -91,10 +90,8 @@ module JsDuck
       @guides = nil
       @videos = nil
       @examples = nil
-      @stats = false
       @categories_path = nil
       @source = true
-      @pretty_json = false
       @images = []
       @link_tpl = '<a href="#!/api/%c%-%m" rel="%c%-%m" class="docClass">%a</a>'
       # Note that we wrap image template inside <p> because {@img} often
@@ -107,8 +104,6 @@ module JsDuck
       @tests = false
 
       # Debugging
-      # Turn multiprocessing off by default in Windows
-      @processes = OS::windows? ? 0 : nil
       @root_dir = File.dirname(File.dirname(File.dirname(__FILE__)))
       @template_dir = @root_dir + "/template-min"
       @template_links = false
@@ -119,9 +114,12 @@ module JsDuck
       @imports = []
       @new_since = nil
 
+      # Turn multiprocessing off by default in Windows
+      Util::Parallel.in_processes = Util::OS::windows? ? 0 : nil
+
       # enable all warnings except :link_auto
-      Logger.instance.set_warning(:all, true)
-      Logger.instance.set_warning(:link_auto, false)
+      Logger.set_warning(:all, true)
+      Logger.set_warning(:link_auto, false)
     end
 
     # Make options object behave like hash.
@@ -172,9 +170,14 @@ module JsDuck
           "TYPE is one of:",
           "",
           "- full     - full class docs.",
-          "- api      - only class- and member names.",
           "- examples - extracts inline examples from classes.") do |format|
-          @export = format.to_sym
+          export_type = format.to_sym
+          if [:full, :examples].include?(export_type)
+            @export = export_type
+          else
+            Logger.fatal("Unsupported export type: '#{export_type}'")
+            exit(1)
+          end
         end
 
         opts.on('--builtin-classes',
@@ -211,7 +214,7 @@ module JsDuck
           if File.exists?(path)
             config = read_json_config(path)
           else
-            Logger.instance.fatal("The config file #{path} doesn't exist")
+            Logger.fatal("The config file #{path} doesn't exist")
             exit(1)
           end
           # treat paths inside JSON config relative to the location of
@@ -336,11 +339,6 @@ module JsDuck
           @tests = true
         end
 
-        opts.on('--stats',
-          "Creates page with all kinds of statistics.") do
-          @stats = true
-        end
-
         opts.on('--import=VERSION:PATH',
           "Imports docs generating @since & @new.",
           "",
@@ -512,7 +510,7 @@ module JsDuck
           "Turns on excessive logging.",
           "",
           "Log messages are writted to STDERR.") do
-          Logger.instance.verbose = true
+          Logger.verbose = true
         end
 
         opts.on('--warnings=+A,-B,+C', Array,
@@ -523,12 +521,12 @@ module JsDuck
           "List of all available warning types:",
           "(Those with '+' in front of them default to on)",
           "",
-          *Logger.instance.doc_warnings) do |warnings|
+          *Logger.doc_warnings) do |warnings|
           warnings.each do |op|
             if op =~ /^([-+]?)(.*)$/
               enable = !($1 == "-")
               name = $2.to_sym
-              Logger.instance.set_warning(name, enable)
+              Logger.set_warning(name, enable)
             end
           end
         end
@@ -543,7 +541,7 @@ module JsDuck
           "results.",
           "",
           "In Windows this option is disabled.") do |count|
-          @processes = count.to_i
+          Util::Parallel.in_processes = count.to_i
         end
 
         opts.on('--pretty-json',
@@ -553,7 +551,7 @@ module JsDuck
           "by --export option.  But the option effects any JSON",
           "that gets generated, so it's also useful when debugging",
           "the resource files generated for the docs app.") do
-          @pretty_json = true
+          Util::Json.pretty = true
         end
 
         opts.on('--template=PATH',
@@ -620,7 +618,7 @@ module JsDuck
     # config options that can be feeded into optparser.
     def read_json_config(fname)
       config = []
-      json = JsonDuck.read(fname)
+      json = Util::Json.read(fname)
       json.each_pair do |key, value|
         if key == "--"
           # filenames
@@ -650,13 +648,13 @@ module JsDuck
           @input_files << fname
         end
       else
-        Logger.instance.warn(nil, "File not found", fname)
+        Logger.warn(nil, "File not found", fname)
       end
     end
 
     # Extracts files of first build in jsb file
     def extract_jsb_files(jsb_file)
-      json = JsonDuck::read(jsb_file)
+      json = Util::Json.read(jsb_file)
       basedir = File.dirname(jsb_file)
 
       return json["builds"][0]["packages"].map do |package_id|
@@ -679,35 +677,35 @@ module JsDuck
     # Runs checks on the options
     def validate
       if @input_files.length == 0 && !@welcome && !@guides && !@videos && !@examples
-        Logger.instance.fatal("You should specify some input files, otherwise there's nothing I can do :(")
+        Logger.fatal("You should specify some input files, otherwise there's nothing I can do :(")
         exit(1)
       elsif @output_dir == :stdout && !@export
-        Logger.instance.fatal("Output to STDOUT only works when using --export option")
+        Logger.fatal("Output to STDOUT only works when using --export option")
         exit(1)
       elsif ![nil, :full, :api, :examples].include?(@export)
-        Logger.instance.fatal("Unknown export format: #{@export}")
+        Logger.fatal("Unknown export format: #{@export}")
         exit(1)
       elsif @output_dir != :stdout
         if !@output_dir
-          Logger.instance.fatal("You should also specify an output directory, where I could write all this amazing documentation")
+          Logger.fatal("You should also specify an output directory, where I could write all this amazing documentation")
           exit(1)
         elsif File.exists?(@output_dir) && !File.directory?(@output_dir)
-          Logger.instance.fatal("The output directory is not really a directory at all :(")
+          Logger.fatal("The output directory is not really a directory at all :(")
           exit(1)
         elsif !File.exists?(File.dirname(@output_dir))
-          Logger.instance.fatal("The parent directory for #{@output_dir} doesn't exist")
+          Logger.fatal("The parent directory for #{@output_dir} doesn't exist")
           exit(1)
         elsif !@export && !File.exists?(@template_dir + "/extjs")
-          Logger.instance.fatal("Oh noes!  The template directory does not contain extjs/ directory :(")
-          Logger.instance.fatal("Please copy ExtJS over to template/extjs or create symlink.")
-          Logger.instance.fatal("For example:")
-          Logger.instance.fatal("    $ cp -r /path/to/ext-4.0.0 " + @template_dir + "/extjs")
+          Logger.fatal("Oh noes!  The template directory does not contain extjs/ directory :(")
+          Logger.fatal("Please copy ExtJS over to template/extjs or create symlink.")
+          Logger.fatal("For example:")
+          Logger.fatal("    $ cp -r /path/to/ext-4.0.0 " + @template_dir + "/extjs")
           exit(1)
         elsif !@export && !File.exists?(@template_dir + "/resources/css")
-          Logger.instance.fatal("Oh noes!  CSS files for custom ExtJS theme missing :(")
-          Logger.instance.fatal("Please compile SASS files in template/resources/sass with compass.")
-          Logger.instance.fatal("For example:")
-          Logger.instance.fatal("    $ compass compile " + @template_dir + "/resources/sass")
+          Logger.fatal("Oh noes!  CSS files for custom ExtJS theme missing :(")
+          Logger.fatal("Please compile SASS files in template/resources/sass with compass.")
+          Logger.fatal("For example:")
+          Logger.fatal("    $ compass compile " + @template_dir + "/resources/sass")
           exit(1)
         end
       end