jsduck 4.10.4 → 5.0.0.beta01

data/lib/jsduck/js/utils.rb

@@ -0,0 +1,21 @@
+module JsDuck
+  module Js
+
+    # Helpers for handling the parsing of Ext.define definitions
+    class Utils
+      # When the value is string, returns the string, otherwise nil
+      def self.make_string(ast)
+        str = ast.to_value
+        str.is_a?(String) ? str : nil
+      end
+
+      # When the value is string or array of strings, returns array of
+      # strings. In any other case, returns empty array.
+      def self.make_string_list(ast)
+        strings = Array(ast.to_value)
+        strings.all? {|s| s.is_a?(String) } ? strings : []
+      end
+    end
+
+  end
+end

data/lib/jsduck/logger.rb

@@ -10,14 +10,8 @@ module JsDuck
     # Set to true to enable verbose logging
     attr_accessor :verbose
 
-    # Set true to force colored output.
-    # Set false to force no colors.
-    attr_accessor :colors
-
     def initialize
       @verbose = false
-      @colors = nil
-
       @warning_docs = [
         [:global, "Member doesn't belong to any class"],
         [:inheritdoc, "@inheritdoc referring to unknown class or member"],
@@ -34,11 +28,12 @@ module JsDuck
         [: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 defined without any values in it"],
+        [:enum, "Enum with invalid values of no values at all"],
 
         [:image, "{@img} referring to missing file"],
         [:image_unused, "An image exists in --images dir that's not used"],
@@ -140,11 +135,6 @@ module JsDuck
       $stderr.puts error.backtrace
     end
 
-    # True when at least one warning was logged.
-    def warnings_logged?
-      @shown_warnings.length > 0
-    end
-
     private
 
     COLORS = {
@@ -165,7 +155,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 @colors == false || @colors == nil && (Util::OS.windows? || !$stderr.tty?)
+      if Util::OS.windows? || !$stderr.tty?
         msg
       else
         COLORS[color_name] + msg + CLEAR

data/lib/jsduck/members_index.rb

@@ -38,7 +38,7 @@ module JsDuck
 
     # Returns array of all local members (excludes inherited ones)
     def all_local
-      local_by_id.values.reject {|m| m[:meta] && m[:meta][:hide] }
+      local_by_id.values.reject {|m| m[:hide] }
     end
 
     # Clears the search cache.
@@ -67,7 +67,7 @@ module JsDuck
         end
 
         # Exclude all non-inheritable static members
-        @global_map_by_id.delete_if {|id, m| m[:meta][:static] && !m[:inheritable] }
+        @global_map_by_id.delete_if {|id, m| m[:static] && !m[:inheritable] }
 
         merge!(@global_map_by_id, local_by_id)
       end
@@ -93,7 +93,7 @@ module JsDuck
     # merges second members hash into first one
     def merge!(hash1, hash2)
       hash2.each_pair do |name, m|
-        if m[:meta] && m[:meta][:hide]
+        if m[:hide]
           if hash1[name]
             hash1.delete(name)
           else
@@ -133,7 +133,6 @@ module JsDuck
           new[:overrides] << {
             :name => old[:name],
             :owner => old[:owner],
-            :id => old[:id],
           }
         end
       end

data/lib/jsduck/merger.rb

@@ -1,178 +1,58 @@
 require 'jsduck/class'
+require 'jsduck/tag_registry'
 
 module JsDuck
 
   # Takes data from comment and code that follows it and combines
   # these two pieces of information into one.  The code comes from
-  # JsDuck::Ast and comment from JsDuck::DocAst.
+  # JsDuck::JS::Ast and comment from JsDuck::Doc::Processor.
   #
   # The main method merge() produces a hash as a result.
   class Merger
 
     # Takes a docset and merges the :comment and :code inside it,
     # producing hash as a result.
-    def merge(docset)
+    def merge(docset, filename="", linenr=0)
       docs = docset[:comment]
       code = docset[:code]
 
-      case docset[:tagname]
-      when :class
-        result = merge_class(docs, code)
-      when :method, :event, :css_mixin
-        result = merge_like_method(docs, code)
-      when :cfg, :property, :css_var
-        result = merge_like_property(docs, code)
-      end
-
-      result[:linenr] = docset[:linenr]
-
-      result
-    end
-
-    private
-
-    def merge_class(docs, code)
-      h = do_merge(docs, code, {
-        :mixins => [],
-        :alternateClassNames => [],
-        :requires => [],
-        :uses => [],
-        :singleton => false,
-      })
-
-      # Ignore extending of the Object class
-      h[:extends] = nil if h[:extends] == "Object"
-
-      h[:aliases] = build_aliases_hash(h[:aliases] || [])
-
-      # Used by Aggregator to determine if we're dealing with Ext4 code
-      h[:code_type] = code[:code_type] if code[:code_type]
-
-      h[:enum] = merge_enum(docs, code) if docs[:enum]
-
-      h[:members] = []
-
-      h
-    end
-
-    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
-
-    def merge_like_property(docs, code)
-      h = do_merge(docs, code)
-
-      h[:type] = merge_if_code_matches(:type, docs, code)
-      if h[:type] == nil
-        h[:type] = code[:tagname] == :method ? "Function" : "Object"
-      end
-
-      h[:default] = merge_if_code_matches(:default, docs, code)
-      h
-    end
-
-    # --- helpers ---
+      h = {
+        :tagname => docset[:tagname],
+        :files => [{:filename => filename, :linenr => linenr}],
+      }
 
-    def do_merge(docs, code, defaults={})
-      h = {}
-      docs.each_pair do |key, value|
-        h[key] = docs[key] || code[key] || defaults[key]
-      end
+      invoke_merge_in_tags(h, docs, code)
+      general_merge(h, docs, code)
 
-      h[:name] = merge_name(docs, code)
+      # Needs to be calculated last, as it relies on the existance of
+      # :name, :static and :tagname fields.
       h[:id] = JsDuck::Class.member_id(h)
 
-      # Copy private to meta
-      h[:meta][:private] = h[:private] if h[:private]
-
-      # Copy :static and :inheritable flags from code if present
-      h[:meta][:static] = true if code[:meta] && code[:meta][:static]
-      h[:inheritable] = true if code[:inheritable]
-
-      # Remember auto-detection info
-      h[:autodetected] = code[:autodetected] if code[:autodetected]
-
       h
     end
 
-    # Given array of full alias names like "foo.bar", "foo.baz"
-    # build hash like {"foo" => ["bar", "baz"]}
-    def build_aliases_hash(aliases)
-      hash={}
-      aliases.each do |a|
-        if a =~ /^([^.]+)\.(.+)$/
-          if hash[$1]
-            hash[$1] << $2
-          else
-            hash[$1] = [$2]
-          end
-        end
-      end
-      hash
-    end
+    private
 
-    def merge_params(docs, code)
-      explicit = docs[:params] || []
-      implicit = code_matches_doc?(docs, code) ? (code[:params] || []) : []
-      # Override implicit parameters with explicit ones
-      # But if explicit ones exist, don't append the implicit ones.
-      params = []
-      (explicit.length > 0 ? explicit.length : implicit.length).times do |i|
-        im = implicit[i] || {}
-        ex = explicit[i] || {}
-        params << {
-          :type => ex[:type] || im[:type] || "Object",
-          :name => ex[:name] || im[:name] || "",
-          :doc => ex[:doc] || im[:doc] || "",
-          :optional => ex[:optional] || false,
-          :default => ex[:default],
-          :properties => ex[:properties] || [],
-        }
+    # Invokes the #merge methods of tags registered for the given
+    # merge context.
+    def invoke_merge_in_tags(h, docs, code)
+      TagRegistry.mergers(h[:tagname]).each do |tag|
+        tag.merge(h, docs, code)
       end
-      params
     end
 
-    def merge_name(docs, code)
-      if docs[:name]
-        docs[:name]
-      elsif code[:name]
-        if docs[:tagname] == :class
-          code[:name]
-        else
-          code[:name].split(/\./).last
-        end
-      else
-        ""
+    # Applies default merge algorithm to the rest of the data.
+    def general_merge(h, docs, code)
+      # Merge in all items in docs that don't occour already in result.
+      docs.each_pair do |key, value|
+        h[key] = value unless h.has_key?(key)
       end
-    end
-
-    def merge_if_code_matches(key, docs, code, default=nil)
-      if docs[key]
-        docs[key]
-      elsif code[key] && code_matches_doc?(docs, code)
-        code[key]
-      else
-        default
+      # Then add all in the items from code not already in result.
+      code.each_pair do |key, value|
+        h[key] = value unless h.has_key?(key)
       end
     end
 
-    # True if the name detected from code matches with explicitly documented name.
-    # Also true when no explicit name documented.
-    def code_matches_doc?(docs, code)
-      return docs[:name] == nil || docs[:name] == code[:name]
-    end
-
-    # Takes the :enum always from docs, but the :doc_only can come
-    # from either code or docs.
-    def merge_enum(docs, code)
-      enum = docs[:enum]
-      enum[:doc_only] = docs[:enum][:doc_only] || (code[:enum] && code[:enum][:doc_only])
-      enum
-    end
-
   end
 
 end

data/lib/jsduck/options.rb

@@ -1,10 +1,11 @@
 require 'jsduck/option_parser'
-require 'jsduck/meta_tag_registry'
 require 'jsduck/logger'
 require 'jsduck/util/json'
 require 'jsduck/util/os'
 require 'jsduck/util/io'
 require 'jsduck/util/parallel'
+require 'jsduck/tag_registry'
+require 'jsduck/js/ext_patterns'
 
 module JsDuck
 
@@ -23,7 +24,6 @@ module JsDuck
     attr_accessor :footer
     attr_accessor :head_html
     attr_accessor :body_html
-    attr_accessor :message
     attr_accessor :welcome
     attr_accessor :guides
     attr_accessor :videos
@@ -40,11 +40,9 @@ module JsDuck
     attr_accessor :tests
     attr_accessor :comments_url
     attr_accessor :comments_domain
-    attr_accessor :search
     attr_accessor :ignore_html
 
     # Debugging
-    attr_accessor :warnings_exit_nonzero
     attr_accessor :template_dir
     attr_accessor :template_links
     attr_accessor :extjs_path
@@ -92,17 +90,15 @@ module JsDuck
         "Mixed",
       ]
       @ext4_events = nil
-      @meta_tag_paths = []
 
-      @version = "4.10.4"
+      @version = "5.0.0.beta01"
 
       # Customizing output
       @title = "Documentation - JSDuck"
       @header = "<strong>Documentation</strong> JSDuck"
-      @footer = format_footer("Generated on {DATE} by {JSDUCK} {VERSION}.")
+      @footer = "Generated with <a href='https://github.com/senchalabs/jsduck'>JSDuck</a> #{@version}."
       @head_html = ""
       @body_html = ""
-      @message = ""
       @welcome = nil
       @guides = nil
       @videos = nil
@@ -110,6 +106,7 @@ module JsDuck
       @categories_path = nil
       @source = true
       @images = []
+      @custom_tag_paths = []
       @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
       # appears inline within text, but that just looks ugly in HTML
@@ -121,11 +118,9 @@ module JsDuck
       @tests = false
       @comments_url = nil
       @comments_domain = nil
-      @search = {}
       @ignore_html = {}
 
       # Debugging
-      @warnings_exit_nonzero = false
       @root_dir = File.dirname(File.dirname(File.dirname(__FILE__)))
       @template_dir = @root_dir + "/template-min"
       @template_links = false
@@ -133,7 +128,6 @@ module JsDuck
       @data_path = nil # This gets assigned in JsDuck::WebWriter after writing the data file.
       @local_storage_db = "docs"
       @touch_examples_ui = false
-      @ext_namespaces = ["Ext"]
       @imports = []
       @new_since = nil
 
@@ -143,31 +137,29 @@ module JsDuck
       # enable all warnings except :link_auto
       Logger.set_warning(:all, true)
       Logger.set_warning(:link_auto, false)
-
-      @optparser = create_option_parser
+      Logger.set_warning(:param_count, false)
     end
 
     # Make options object behave like hash.
     # This allows us to substitute it with hash in unit tests.
     def [](key)
-      send(key)
+      instance_variable_get("@#{key}")
+    end
+    def []=(key, value)
+      instance_variable_set("@#{key}", value)
     end
 
     def parse!(argv)
-      parse_options(argv)
-      auto_detect_config_file
+      create_option_parser.parse!(argv).each do |fname|
+        read_filenames(canonical(fname))
+      end
       validate
 
-      reg = MetaTagRegistry.new
-      reg.load([:builtins] + @meta_tag_paths)
-      reg[:new].create_tooltip!(@imports, @new_since)
-      MetaTagRegistry.instance = reg
+      @custom_tag_paths.each {|path| TagRegistry.load_from(path) }
     end
 
-    private
-
     def create_option_parser
-      return JsDuck::OptionParser.new do | opts |
+      optparser = JsDuck::OptionParser.new do | opts |
         opts.banner = "Usage: jsduck [options] files/dirs..."
         opts.separator ""
         opts.separator "For example:"
@@ -235,9 +227,6 @@ module JsDuck
           "",
           "An alternative to listing all options on command line.",
           "",
-          "When the current directory contains jsduck.json file",
-          "then options are automatically read from there.",
-          "",
           "See also: https://github.com/senchalabs/jsduck/wiki/Config-file") do |path|
           path = canonical(path)
           if File.exists?(path)
@@ -249,7 +238,7 @@ module JsDuck
           # treat paths inside JSON config relative to the location of
           # config file.  When done, switch back to current working dir.
           @working_dir = File.dirname(path)
-          parse_options(config)
+          optparser.parse!(config).each {|fname| read_filenames(canonical(fname)) }
           @working_dir = nil
         end
 
@@ -276,14 +265,11 @@ module JsDuck
         opts.on('--footer=TEXT',
           "Custom footer text for the documentation.",
           "",
-          "The text can contain various placeholders:",
-          "",
-          "  {DATE} - current date and time.",
-          "  {JSDUCK} - link to JSDuck homepage.",
-          "  {VERSION} - JSDuck version number.",
+          "Defaults to: 'Generated with JSDuck {VERSION}.'",
           "",
-          "Defaults to: 'Generated on {DATE} by {JSDUCK} {VERSION}.'") do |text|
-          @footer = format_footer(text)
+          "'{VERSION}' is a placeholder that will get substituted",
+          "with the current version of JSDuck.  See --version.") do |text|
+          @footer = text.gsub(/\{VERSION\}/, @version)
         end
 
         opts.on('--head-html=HTML',
@@ -306,15 +292,6 @@ module JsDuck
           @body_html += html
         end
 
-        opts.on('--message=HTML',
-          "(Warning) message to show prominently.",
-          "",
-          "Useful for warning users that they are viewing an old",
-          "version of the docs, and prividing a link to the new",
-          "version.") do |html|
-          @message += html
-        end
-
         opts.on('--welcome=PATH',
           "File with content for welcome page.",
           "",
@@ -401,7 +378,7 @@ module JsDuck
           "a @new tag (unless --new-since option is used).",
           "",
           "See also: https://github.com/senchalabs/jsduck/wiki/@since") do |v|
-          if v =~ /\A(.*?):(.*)\Z/
+          if v =~ /\A(.*?):(.*)\z/
             @imports << {:version => $1, :path => canonical($2)}
           else
             @imports << {:version => v}
@@ -428,8 +405,6 @@ module JsDuck
         end
 
         opts.on('--comments-domain=STRING',
-          "A name identifying the subset of comments.",
-          "",
           "A string consisting of <name>/<version>.",
           "",
           "For example: ext-js/4",
@@ -438,51 +413,20 @@ module JsDuck
           @comments_domain = domain
         end
 
-        opts.on('--search-url=URL',
-          "Address of guides search server.",
-          "",
-          "When supplied, the search for guides is performed through this",
-          "external service and the results merged together with API search.",
-          "The search server must respond to JSONP requests.",
-          "",
-          "For example: http://sencha.com/docsearch",
-          "",
-          "Must be used together with --search-domain option.",
-          "",
-          "This option is EXPERIMENTAL.") do |url|
-          @search[:url] = url
-        end
-
-        opts.on('--search-domain=STRING',
-          "A name identifying the subset to search from.",
-          "",
-          "A string consisting of <name>/<version>.",
-          "",
-          "Tells the search engine which product and version",
-          "to include into search.",
-          "",
-          "For example: Ext JS/4.2.0",
-          "",
-          "Must be used together with --search-url option.",
-          "",
-          "This option is EXPERIMENTAL.") do |domain|
-          @search[:product], @search[:version] = domain.split(/\//)
-        end
-
         opts.separator ""
         opts.separator "Tweaking:"
         opts.separator ""
 
-        opts.on('--meta-tags=PATH',
-          "Path to custom meta-tag implementations.",
+        opts.on('--tags=PATH',
+          "Path to custom tag implementations.",
           "",
           "Can be a path to single Ruby file or a directory.",
           "",
           "This option can be used repeatedly to include multiple",
-          "meta tags from different places.",
+          "tags from different places.",
           "",
           "See also: https://github.com/senchalabs/jsduck/wiki/Custom-tags") do |path|
-          @meta_tag_paths << canonical(path)
+          @custom_tag_paths << canonical(path)
         end
 
         opts.on('--ignore-global',
@@ -590,8 +534,8 @@ module JsDuck
           "In such case pass --ext-namespaces=Ext,YourNS option",
           "and JSDuck will recognize both Ext.define() and",
           "YourNs.define() plus few other things that depend on",
-          "Ext namespace like Ext.emptyFn.") do |ns|
-          @ext_namespaces = ns
+          "Ext namespace like Ext.emptyFn.") do |namespaces|
+          Js::ExtPatterns.set(namespaces)
         end
 
         opts.on('--touch-examples-ui',
@@ -624,7 +568,7 @@ module JsDuck
         opts.on('-v', '--verbose',
           "Turns on excessive logging.",
           "",
-          "Log messages are written to STDERR.") do
+          "Log messages are writted to STDERR.") do
           Logger.verbose = true
         end
 
@@ -646,26 +590,6 @@ module JsDuck
           end
         end
 
-        opts.on('--warnings-exit-nonzero',
-          "Exits with non-zero exit code on warnings.",
-          "",
-          "By default JSDuck only exits with non-zero exit code",
-          "when a fatal error is encountered (code 1).",
-          "",
-          "With this option the exit code will be 2 when any warning",
-          "gets printed.") do
-          @warnings_exit_nonzero = true
-        end
-
-        opts.on('--[no-]color',
-          "Turn on/off colorized terminal output.",
-          "",
-          "By default the colored output is on, but gets disabled",
-          "automatically when output is not an interactive terminal",
-          "(or when running on Windows system).") do |on|
-          Logger.colors = on
-        end
-
         opts.on('-p', '--processes=COUNT',
           "The number of parallel processes to use.",
           "",
@@ -704,14 +628,6 @@ module JsDuck
           @template_links = true
         end
 
-        opts.on('-d', '--debug',
-          "Same as --template=template --template-links.",
-          "",
-          "Useful shorthand during development.") do
-          @template_dir = canonical("template")
-          @template_links = true
-        end
-
         opts.on('--extjs-path=PATH',
           "Path for main ExtJS JavaScript file.",
           "",
@@ -753,20 +669,8 @@ module JsDuck
           exit
         end
       end
-    end
-
-    # Parses the given command line options
-    # (could have also been read from config file)
-    def parse_options(options)
-      @optparser.parse!(options).each {|fname| read_filenames(canonical(fname)) }
-    end
 
-    # Reads jsduck.json file in current directory
-    def auto_detect_config_file
-      fname = Dir.pwd + "/jsduck.json"
-      if File.exists?(fname)
-        parse_options(read_json_config(fname))
-      end
+      return optparser
     end
 
     # Reads JSON configuration from file and returns an array of
@@ -829,13 +733,6 @@ module JsDuck
       File.expand_path(path, @working_dir)
     end
 
-    # Replace special placeholders in footer text
-    def format_footer(text)
-      jsduck = "<a href='https://github.com/senchalabs/jsduck'>JSDuck</a>"
-      date = Time.new.strftime('%a %d %b %Y %H:%M:%S')
-      text.gsub(/\{VERSION\}/, @version).gsub(/\{JSDUCK\}/, jsduck).gsub(/\{DATE\}/, date)
-    end
-
     # Runs checks on the options
     def validate
       if @input_files.length == 0 && !@welcome && !@guides && !@videos && !@examples