solvas-jsduck 6.0.0.beta.1888

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/enums.rb

@@ -0,0 +1,90 @@
+require 'jsduck/logger'
+
+module JsDuck
+  module Process
+
+    class Enums
+      def initialize(classes_hash)
+        @classes_hash = classes_hash
+      end
+
+      # Applies additional processing to all enum-classes.
+      def process_all!
+        @classes_hash.each_value do |cls|
+          if cls[:enum]
+            process(cls)
+          end
+        end
+      end
+
+      private
+
+      # processes single class
+      def process(cls)
+        expand_default(cls)
+        reject_not_properties(cls)
+        strip_inheritdoc(cls)
+        cls[:enum][:type] = infer_type(cls) unless cls[:enum][:type]
+      end
+
+      # Expands default value like widget.* into list of properties
+      def expand_default(cls)
+        if cls[:enum][:default] =~ /\A(.*)\.\*\z/
+          each_alias($1) do |name, owner|
+            cls[:members] << {
+              :tagname => :property,
+              :id => 'property-' + name,
+              :name => name,
+              :default => "'" + name + "'",
+              :type => "String",
+              :private => owner[:private],
+              :files => cls[:files],
+              :owner => cls[:name],
+              :doc => "Alias for {@link #{owner[:name]}}.",
+            }
+          end
+        end
+      end
+
+      def each_alias(prefix)
+        @classes_hash.each_value do |cls|
+          if cls[:aliases] && cls[:aliases][prefix]
+            cls[:aliases][prefix].each {|name| yield(name, cls) }
+          end
+        end
+      end
+
+      # Only allow properties as members, throw away all others.
+      def reject_not_properties(cls)
+        cls[:members].reject! do |m|
+          if m[:tagname] == :property
+            false
+          else
+            Logger.warn(:enum, "Enums can only contain properties, #{m[:tagname]} found instead.", m[:files][0])
+            true
+          end
+        end
+      end
+
+      # Remove the auto-inserted inheritdoc tag so the auto-detected enum
+      # values default to being public.
+      def strip_inheritdoc(cls)
+        cls[:members].each do |p|
+          p[:inheritdoc] = nil if p[:autodetected] && p[:autodetected][:tagname]
+        end
+      end
+
+      # Given an enum class, returns the type infered from its values.
+      def infer_type(cls)
+        if cls[:members].length > 0
+          types = cls[:members].map {|p| p[:type] }
+          types.sort.uniq.join("/")
+        else
+          "Object"
+        end
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/process/ext4_events.rb

@@ -0,0 +1,46 @@
+require 'ostruct'
+
+module JsDuck
+  module Process
+
+    # Appends Ext4 options parameter to the parameter list of each event
+    # in each class.
+    #
+    # 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=OpenStruct.new)
+        @classes = classes
+        @opts = opts
+      end
+
+      def process_all!
+        if @opts.ext4_events == true || (@opts.ext4_events == nil && ext4_style_code?)
+          @classes.each_value {|cls| process(cls) }
+        end
+      end
+
+      # Are we dealing with code looking like ExtJS 4?
+      # True if any of the classes is defined with Ext.define()
+      def ext4_style_code?
+        @classes.values.any? {|cls| cls[:code_type] == :ext_define }
+      end
+
+      def process(cls)
+        cls[:members].each do |m|
+          m[:params] << OPTIONS if m[:tagname] == :event
+        end
+      end
+
+      OPTIONS = {
+        :tagname => :params,
+        :name => "eOpts",
+        :type => "Object",
+        :doc => "The options object passed to {@link Ext.util.Observable#addListener}.",
+        :ext4_auto_param => true,
+      }
+
+    end
+
+  end
+end

data/lib/jsduck/process/fires.rb

@@ -0,0 +1,71 @@
+require 'jsduck/logger'
+
+module JsDuck
+  module Process
+
+    # Expands lists of fired events to take into account events fired
+    # by all the methods that get called by a method.
+    class Fires
+      def initialize(relations)
+        @relations = relations
+        # Map of methods for which all @fires tags have been detected.
+        # So we don't repeat the resolving.
+        @detected = {}
+        # Map of methods that we're currently resolving.
+        # So we don't recurse into infinity.
+        @call_chain = {}
+      end
+
+      # Populates @fires tags with additional events.
+      def process_all!
+        @relations.each do |cls|
+          cls.find_members(:tagname => :method, :static => false).each do |m|
+            @call_chain = {m[:name] => true}
+            detect_fires(cls, m)
+          end
+        end
+      end
+
+      private
+
+      def detect_fires(cls, m)
+        if m[:autodetected][:fires] && m[:method_calls] && !detected?(m)
+          m[:fires] = events_from_methods(cls, m[:method_calls]).concat(m[:fires] || []).sort.uniq
+          mark_detected(m)
+        end
+
+        m[:fires]
+      end
+
+      def mark_detected(m)
+        @detected[m[:owner]] = {} unless @detected[m[:owner]]
+        @detected[m[:owner]][m[:name]] = true
+      end
+
+      def detected?(m)
+        cls = @detected[m[:owner]]
+        cls && cls[m[:name]]
+      end
+
+      def events_from_methods(cls, methods)
+        events = []
+
+        methods.each do |name|
+          if !@call_chain[name]
+            @call_chain[name] = true
+            m = cls.find_members(:tagname => :method, :name => name, :static => false)[0]
+            if m
+              fires = detect_fires(cls, m)
+              events.concat(fires) if fires
+            end
+            @call_chain[name] = false
+          end
+        end
+
+        events.sort.uniq
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/process/global_members.rb

@@ -0,0 +1,35 @@
+require 'jsduck/logger'
+
+module JsDuck
+  module Process
+
+    # Prints warning for each global member.
+    # Removes "global" class when --ignore-global option used.
+    # Warnings for global members are printed regardless of that setting,
+    # but of course can be turned off using --warnings=-global
+    class GlobalMembers
+      def initialize(classes_hash, opts)
+        @classes_hash = classes_hash
+        @opts = opts
+      end
+
+      def process_all!
+        # Do nothing when there's no "global" class.
+        return unless @classes_hash["global"]
+
+        # Warnings for each global member
+        @classes_hash["global"][:members].each do |m|
+          type = m[:tagname].to_s
+          name = m[:name]
+          Logger.warn(:global, "Global #{type}: #{name}", m[:files][0])
+        end
+
+        # Throw away the "global" class when --ignore-global option used
+        if @opts.ignore_global
+          @classes_hash.delete("global")
+        end
+      end
+    end
+
+  end
+end

data/lib/jsduck/process/ignored_classes.rb

@@ -0,0 +1,16 @@
+module JsDuck
+  module Process
+
+    # Gets rid of classes marked with @ignore
+    class IgnoredClasses
+      def initialize(classes_hash)
+        @classes_hash = classes_hash
+      end
+
+      def process_all!
+        @classes_hash.delete_if {|name, cls| cls[:ignore] }
+      end
+    end
+
+  end
+end

data/lib/jsduck/process/importer.rb

@@ -0,0 +1,75 @@
+require 'jsduck/util/json'
+require 'jsduck/util/null_object'
+require 'jsduck/util/parallel'
+require 'jsduck/logger'
+
+module JsDuck
+  module Process
+
+    # Reads in JSDuck exports of different versions of docs.
+    class Importer
+      # Reads in data for all versions, returning array of
+      # version/class-data pairs.  We don't use a hash to preserve the
+      # order of versions (from oldest to newest).
+      def import(versions)
+        versions.map do |ver|
+          {
+            :version => ver[:version],
+            :classes => ver[:path] ? read(ver) : current_version,
+          }
+        end
+      end
+
+      private
+
+      def current_version
+        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
+      def read(ver)
+        ensure_correct_format(ver[:path])
+
+        # Map list of files into pairs of (classname, members-hash)
+        pairs = Util::Parallel.map(Dir[ver[:path] + "/*.json"]) do |filename|
+          Logger.log("Importing #{ver[:version]}", filename)
+          json = Util::Json.read(filename)
+          [json["name"],  members_id_index(json)]
+        end
+
+        # Turn key-value pairs array into hash
+        return Hash[ pairs ]
+      end
+
+      def ensure_correct_format(path)
+        # Read first JSON file in import dir
+        json = Util::Json.read(Dir[path + "/*.json"].first)
+
+        unless correct_format?(json)
+          Logger.fatal("Bad format for importing: #{path}")
+          Logger.fatal("Export format changed in 5.0.0 beta 2.")
+          Logger.fatal("Maybe you forgot to re-generate the exports with new JSDuck.")
+          exit(1)
+        end
+      end
+
+      def correct_format?(json)
+        json["members"].is_a?(Array)
+      end
+
+      # creates index of all class members
+      def members_id_index(json)
+        index = {}
+        json["members"].each do |m|
+          index[m["id"]] = m["params"] ? m["params"].map {|p| p["name"] } : true
+        end
+        index
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/process/inherit_class.rb

@@ -0,0 +1,58 @@
+require 'jsduck/logger'
+
+module JsDuck
+  module Process
+
+    # Deals with inheriting class documentation.
+    class InheritClass
+      def initialize(relations)
+        @relations = relations
+      end
+
+      # Inherits docs for class.
+      #
+      # For class we only inherit the value of :doc field.
+      #
+      # When the class we're inheriting from also has @inheritdoc tag,
+      # we first recursively resolve the inheritance of that class and
+      # only afterwards inherit to the current class.
+      def resolve(cls)
+        return unless cls[:inheritdoc]
+
+        parent = find_parent(cls)
+        if parent && parent[:inheritdoc]
+          resolve(parent)
+        end
+
+        if parent
+          cls[:doc] = parent[:doc] if cls[:doc].empty?
+        end
+
+        cls[:inheritdoc] = nil
+      end
+
+      private
+
+      def find_parent(cls)
+        if cls[:inheritdoc][:cls]
+          # @inheritdoc MyClass
+          parent = @relations[cls[:inheritdoc][:cls]]
+          return warn("class not found", cls) unless parent
+        else
+          # @inheritdoc
+          parent = cls.parent
+          return warn("parent class not found", cls) unless parent
+        end
+
+        return parent
+      end
+
+      def warn(msg, cls)
+        Logger.warn(:inheritdoc, "@inheritdoc #{cls[:inheritdoc][:cls]} - #{msg}", cls[:files][0])
+        return nil
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/process/inherit_doc.rb

@@ -0,0 +1,32 @@
+require 'jsduck/logger'
+require 'jsduck/class'
+require 'jsduck/process/inherit_class'
+require 'jsduck/process/inherit_members'
+
+module JsDuck
+  module Process
+
+    # Deals with inheriting documentation
+    class InheritDoc
+      def initialize(relations)
+        @relations = relations
+        @inherit_class = InheritClass.new(@relations)
+        @inherit_members = InheritMembers.new(@relations)
+      end
+
+      # Performs all inheriting
+      def process_all!
+        @relations.each do |cls|
+          @inherit_class.resolve(cls)
+          @inherit_members.resolve(cls)
+        end
+
+        @relations.each do |cls|
+          cls.refresh_member_ids!
+        end
+      end
+
+    end
+
+  end
+end