jsduck 5.3.4 → 6.0.0beta

data/lib/jsduck/options/processor.rb

@@ -0,0 +1,47 @@
+require 'jsduck/options/parser'
+require 'jsduck/options/input_files'
+require 'jsduck/logger'
+require 'jsduck/util/json'
+require 'jsduck/util/io'
+require 'jsduck/util/parallel'
+require 'jsduck/tag_registry'
+require 'jsduck/js/ext_patterns'
+
+module JsDuck
+  module Options
+
+    # A facade for all the command line options processing.
+    class Processor
+      # Takes a list of command line options, parses it to an
+      # Options::Record object, validates the options, applies it to
+      # various singleton classes and returns the Options::Record.
+      def self.process(args)
+        # HACK! First establish warnings defaults.
+        Logger.configure_defaults
+
+        opts = Options::Parser.new.parse(args)
+
+        # Expand list of input files
+        Options::InputFiles.new(opts).expand!
+
+        # Validate the options.
+        # Exit program when there's an error.
+        if err = opts.validate!
+          Array(err).each {|line| Logger.fatal(line) }
+          exit(1)
+        end
+
+        # Configure various objects with these options
+        Logger.configure(opts)
+        Util::Parallel.configure(opts)
+        TagRegistry.configure(opts)
+        Js::ExtPatterns.configure(opts)
+        Util::Json.configure(opts)
+        Util::IO.configure(opts)
+
+        opts
+      end
+    end
+
+  end
+end

data/lib/jsduck/options/record.rb

@@ -0,0 +1,51 @@
+module JsDuck
+  module Options
+
+    # Stores values of command line options.
+    #
+    # All options are initially defined with an #attribute method, which
+    # ensures that accessing an unexisting option will result in an
+    # error.
+    class Record
+      def initialize
+        @validators = {}
+      end
+
+      # Defines accessor for an option,
+      # and assigns a default value for it.
+      def attribute(name, default=nil)
+        instance_variable_set("@#{name}", default)
+        # Use `send` to invoke private attr_accessor method.  As we only
+        # expect a single OptionsRecord to exist for the lifetime of the
+        # app, it should be safe to define a method on a class.
+        self.class.send(:attr_accessor, name)
+      end
+
+      # Defines a validator function that gets run after all the
+      # options have been parsed.  When validation fails, the function
+      # should return an error message string (or an array of string
+      # for multi-line error message) otherwise nil, to signify
+      # success.
+      def validator(name, &block)
+        @validators[name] = block
+      end
+
+      # Runs all the validators.  Returns an error message string from
+      # the first failed validation or nil when everything is OK.
+      #
+      # Alternatively runs just one validator by name. Used in testing.
+      def validate!(name=nil)
+        validators = name ? [@validators[name]] : @validators.values
+
+        validators.each do |block|
+          if err = block.call()
+            return err
+          end
+        end
+        return nil
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/output_dir.rb

@@ -11,18 +11,18 @@ module JsDuck
     def self.clean(opts)
       if opts.cache && cache_dir_needs_preserving(opts)
         # Remove all files inside <output-dir> except .cache/
-        Dir[opts.output_dir + "/*"].each do |file|
+        Dir[opts.output + "/*"].each do |file|
           FileUtils.rm_rf(file) unless file =~ /\/.cache\z/
         end
       else
         # Remove and recreate the entire <output-dir>
-        FileUtils.rm_rf(opts.output_dir)
-        FileUtils.mkdir(opts.output_dir)
+        FileUtils.rm_rf(opts.output)
+        FileUtils.mkdir(opts.output)
       end
     end
 
     def self.cache_dir_needs_preserving(opts)
-      opts.cache_dir == opts.output_dir + "/.cache" && File.exists?(opts.cache_dir)
+      opts.cache_dir == opts.output + "/.cache" && File.exists?(opts.cache_dir)
     end
 
   end

data/lib/jsduck/parser.rb

@@ -9,7 +9,7 @@ require 'jsduck/base_type'
 require 'jsduck/class_doc_expander'
 
 module JsDuck
-  # Performs the actual parsing of CSS or JS source.
+  # Performs the actual parsing of SCSS or JS source.
   #
   # This is the class that brings together all the different steps of
   # parsing the source.
@@ -27,7 +27,7 @@ module JsDuck
     def parse(contents, filename="", options={})
       @doc_processor.filename = @filename = filename
 
-      parse_js_or_css(contents, filename, options).map do |docset|
+      parse_js_or_scss(contents, filename, options).map do |docset|
         expand(docset)
       end.flatten.map do |docset|
         merge(docset)
@@ -36,9 +36,9 @@ module JsDuck
 
     private
 
-    # Parses the file depending on filename as JS or CSS
-    def parse_js_or_css(contents, filename, options)
-      if filename =~ /\.s?css$/
+    # Parses the file depending on filename as JS or SCSS
+    def parse_js_or_scss(contents, filename, options)
+      if filename =~ /\.scss$/
         docs = Css::Parser.new(contents, options).parse
       else
         docs = Js::Parser.new(contents, options).parse

data/lib/jsduck/process/components.rb

@@ -0,0 +1,19 @@
+module JsDuck
+  module Process
+
+    # Auto-detects classes inheriting from Ext.Component, and marks
+    # them as :component.
+    class Components
+      def initialize(relations)
+        @relations = relations
+      end
+
+      def process_all!
+        @relations.each do |cls|
+          cls[:component] = true if cls.inherits_from?("Ext.Component")
+        end
+      end
+    end
+
+  end
+end

data/lib/jsduck/process/ext4_events.rb

@@ -1,3 +1,5 @@
+require 'ostruct'
+
 module JsDuck
   module Process
 
@@ -7,13 +9,13 @@ module JsDuck
     # But only does so when :ext4_events option is set to true or the
     # code itself is detected as being writted in Ext4 style.
     class Ext4Events
-      def initialize(classes, opts={})
+      def initialize(classes, opts=OpenStruct.new)
         @classes = classes
         @opts = opts
       end
 
       def process_all!
-        if @opts[:ext4_events] == true || (@opts[:ext4_events] == nil && ext4_style_code?)
+        if @opts.ext4_events == true || (@opts.ext4_events == nil && ext4_style_code?)
           @classes.each_value {|cls| process(cls) }
         end
       end

data/lib/jsduck/process/importer.rb

@@ -23,7 +23,10 @@ module JsDuck
       private
 
       def current_version
-        Util::NullObject.new(:[] => Util::NullObject.new(:[] => true))
+        JsDuck::Util::NullObject.new(
+          :[] => JsDuck::Util::NullObject.new( # class
+            :[] => JsDuck::Util::NullObject.new( # member
+              :length => 1.0 / 0))) # params count == Infinity
       end
 
       # Reads in data from all .json files in directory
@@ -61,7 +64,7 @@ module JsDuck
       def members_id_index(json)
         index = {}
         json["members"].each do |m|
-          index[m["id"]] = true
+          index[m["id"]] = m["params"] ? m["params"].map {|p| p["name"] } : true
         end
         index
       end

data/lib/jsduck/process/inherit_members.rb

@@ -19,6 +19,7 @@ module JsDuck
       # - :params
       # - :return
       # - :throws
+      # - :properties
       #
       # In case of auto-detected members that inherit from a public
       # member in parent class, we inherit all fields that aren't
@@ -82,6 +83,7 @@ module JsDuck
         m[:params] = parent[:params] if inherit_params?(m, parent)
         m[:return] = parent[:return] unless m[:return]
         m[:throws] = parent[:throws] unless m[:throws] && m[:throws].length > 0
+        m[:properties] = parent[:properties] unless m[:properties] && m[:properties].length > 0
 
         # Don't inherit type from parent when:
         # - member itself has type and it's not auto-detected

data/lib/jsduck/process/lint.rb

@@ -27,7 +27,7 @@ module JsDuck
           if !member[:name] || member[:name] == ""
             warn(:name_missing, "Unnamed #{member[:tagname]}", member)
           end
-          (member[:params] || []).each do |p|
+          Array(member[:params]).each do |p|
             if !p[:name] || p[:name] == ""
               warn(:name_missing, "Unnamed parameter", member)
             end
@@ -40,7 +40,7 @@ module JsDuck
         each_member do |member|
           if member[:tagname] == :method
             optional_found = false
-            member[:params].each do |p|
+            Array(member[:params]).each do |p|
               if optional_found && !p[:optional]
                 warn(:req_after_opt, "Optional param followed by regular param #{p[:name]}", member)
               end
@@ -54,7 +54,7 @@ module JsDuck
       def warn_duplicate_params
         each_member do |member|
           params = {}
-          (member[:params] || []).each do |p|
+          Array(member[:params]).each do |p|
             if params[p[:name]]
               warn(:dup_param, "Duplicate parameter name #{p[:name]}", member)
             end

data/lib/jsduck/process/no_doc.rb

@@ -41,7 +41,7 @@ module JsDuck
       def warn(type, msg, owner)
         visibility = owner[:private] ? :private : (owner[:protected] ? :protected : :public)
 
-        Logger.warn_nodoc(type, visibility, msg, owner[:files][0])
+        Logger.warn(:nodoc, msg, owner[:files][0], [type, visibility])
       end
 
     end

data/lib/jsduck/process/overrides.rb

@@ -1,17 +1,18 @@
 require 'jsduck/logger'
+require 'ostruct'
 
 module JsDuck
   module Process
 
     class Overrides
-      def initialize(classes_hash, opts = {:external_classes => []})
+      def initialize(classes_hash, opts = OpenStruct.new(:external => []))
         @classes_hash = classes_hash
         @opts = opts
       end
 
       # Applies all override classes to target classes, then deletes
       # the overrides themselves from classes hash and adds the names
-      # of all the processed overrides to external_classes list in
+      # of all the processed overrides to external classes list in
       # options object.
       def process_all!
         overrides = []
@@ -28,7 +29,7 @@ module JsDuck
           @classes_hash.delete(cls[:name])
         end
 
-        @opts[:external_classes] += overrides.map {|c| c[:name] }
+        @opts.external += overrides.map {|c| c[:name] }
       end
 
       private

data/lib/jsduck/process/versions.rb

@@ -1,5 +1,5 @@
 require 'jsduck/process/importer'
-require 'jsduck/tag_registry'
+require 'ostruct'
 
 module JsDuck
   module Process
@@ -7,76 +7,65 @@ module JsDuck
     # Generates @since and @new tags by importing JSDuck exports of
     # older versions of the same project and looking in which version
     # a class or method first appeared.
-    #
-    # Additionally here the tooltip text for @new tag gets injected.
     class Versions
-      def initialize(relations, opts={}, importer=nil)
+      def initialize(relations, opts=OpenStruct.new, importer=Process::Importer.new)
         @relations = relations
         @opts = opts
-        # Allow different importer to be injected for testing
-        @importer = importer || Process::Importer.new
+        @importer = importer
       end
 
       # Loads in exported docs and generates @since and @new tags.
       def process_all!
-        init_new_tag_tooltip!
-
-        if @opts[:imports].length > 0
-          generate_since_tags(@importer.import(@opts[:imports]))
+        if @opts.import.length > 0
+          @versions = @importer.import(@opts.import)
+          add_since_tags
         end
       end
 
       private
 
-      # Initializes the tooltip text for the signature of @new tag.
-      def init_new_tag_tooltip!
-        signature = TagRegistry.get_by_name(:new).signature
-        if @opts[:new_since]
-          signature[:tooltip] = "New since #{@opts[:new_since]}"
-        elsif @opts[:imports].length > 0
-          signature[:tooltip] = "New since #{@opts[:imports].last[:version]}"
-        end
-      end
+      # classes...
 
       # Using the imported versions data, adds @since tags to all
-      # classes/members.
-      def generate_since_tags(versions)
-        new_versions = build_new_versions_map(versions)
-
+      # classes/members/params.
+      def add_since_tags
         @relations.each do |cls|
-          v = cls[:since] || class_since(versions, cls)
+          v = cls[:since] || class_since(cls)
           cls[:since] = v
-          cls[:new] = true if new_versions[v]
+          cls[:new] = true if is_new?(v)
 
-          cls.all_local_members.each do |m|
-            v = m[:since] || member_since(versions, cls, m)
-            m[:since] = v
-            m[:new] = true if new_versions[v]
-          end
+          add_members_since_tags(cls)
         end
       end
 
-      # Generates a lookup table of versions that we are going to label
-      # with @new tags.  By default we use the latest version, otherwise
-      # use all versions since the latest.
-      def build_new_versions_map(versions)
-        new_versions = {}
-
-        if @opts[:new_since]
-          versions.map {|v| v[:version] }.each do |v|
-            if v == @opts[:new_since] || !new_versions.empty?
-              new_versions[v] = true
-            end
+      # Returns name of the version since which the class is available
+      def class_since(cls)
+        @versions.each do |ver|
+          return ver[:version] if ver[:classes][cls[:name]]
+          cls[:alternateClassNames].each do |name|
+            return ver[:version] if ver[:classes][name]
           end
-        else
-          new_versions[versions.last[:version]] = true
         end
+      end
 
-        new_versions
+      # members...
+
+      def add_members_since_tags(cls)
+        cls.all_local_members.each do |m|
+          # Remember the initial explicit @since tag value
+          # to disable params processing when it's present.
+          explicit_since = m[:since]
+
+          v = m[:since] || member_since(cls, m)
+          m[:since] = v
+          m[:new] = true if is_new?(v)
+
+          add_params_since_tags(cls, m, v) unless explicit_since
+        end
       end
 
-      def member_since(versions, cls, m)
-        versions.each do |ver|
+      def member_since(cls, m)
+        @versions.each do |ver|
           c = ver[:classes][cls[:name]]
           return ver[:version] if c && c[m[:id]]
           cls[:alternateClassNames].each do |name|
@@ -86,14 +75,60 @@ module JsDuck
         end
       end
 
-      # Returns name of the version since which the class is available
-      def class_since(versions, cls)
-        versions.each do |ver|
-          return ver[:version] if ver[:classes][cls[:name]]
+      # params...
+
+      def add_params_since_tags(cls, member, member_version)
+        Array(member[:params]).each_with_index do |p, i|
+          v = param_since(cls, member, i)
+          if v != member_version
+            p[:since] = v
+            p[:new] = true if is_new?(v)
+          end
+        end
+      end
+
+      def param_since(cls, m, i)
+        @versions.each do |ver|
+          c = ver[:classes][cls[:name]]
+          return ver[:version] if c && has_param?(c[m[:id]], i)
           cls[:alternateClassNames].each do |name|
-            return ver[:version] if ver[:classes][name]
+            c = ver[:classes][name]
+            return ver[:version] if c && has_param?(c[m[:id]], i)
+          end
+        end
+      end
+
+      # Because parameters can be renamed between versions, only
+      # consider parameter count.
+      def has_param?(member, param_index)
+        member && member.respond_to?(:length) && member.length > param_index
+      end
+
+      # helpers...
+
+      # Should items introduced in given version be marked as new?
+      def is_new?(version_nr)
+        @new_versions = new_versions_map unless @new_versions
+        @new_versions[version_nr]
+      end
+
+      # Generates a lookup table of versions that we are going to label
+      # with @new tags.  By default we use the latest version, otherwise
+      # use all versions since the latest.
+      def new_versions_map
+        new_versions = {}
+
+        if @opts.new_since
+          @versions.map {|v| v[:version] }.each do |v|
+            if v == @opts.new_since || !new_versions.empty?
+              new_versions[v] = true
+            end
           end
+        else
+          new_versions[@versions.last[:version]] = true
         end
+
+        new_versions
       end
 
     end