jsduck 5.0.0.beta01 → 5.0.0.beta2

data/lib/jsduck/process/accessors.rb

@@ -3,6 +3,17 @@ require 'jsduck/logger'
 module JsDuck
   module Process
 
+    # Expands accessors.
+    #
+    # Looks up configs with @accessor tag (or configs defined inside
+    # config: {} or eventedConfig: {} block).
+    #
+    # For such config "foo" it generates:
+    #
+    # - getter "getFoo"
+    # - setter "setFoo"
+    # - event "foochange" (when tagged with @evented)
+    #
     class Accessors
       def initialize(classes)
         @classes = classes
@@ -13,6 +24,8 @@ module JsDuck
         @classes.each_value {|cls| process(cls) }
       end
 
+      private
+
       # Given a class, generates accessor methods to configs with
       # @accessor tag.  Modifies the class by adding these methods.
       # When class already contains a getter or setter, the method is
@@ -113,15 +126,15 @@ module JsDuck
           }, cfg)
       end
 
+      # Copy over from @cfg all the fields that aren't already present.
+      # Except :type and :default which don't make sense for methods and events.
       def add_shared(hash, cfg)
-        hash.merge!({
-            :owner => cfg[:owner],
-            :files => cfg[:files],
-            :private => cfg[:private],
-            :protected => cfg[:protected],
-            :autodetected => cfg[:autodetected],
-            :hide => cfg[:hide],
-          })
+        ignored_fields = [:type, :default, :accessor, :evented]
+
+        cfg.each_pair do |key, value|
+          hash[key] = value unless ignored_fields.include?(key) || hash[key]
+        end
+        hash
       end
 
       def upcase_first(str)

data/lib/jsduck/process/enums.rb

@@ -60,8 +60,7 @@ module JsDuck
           if m[:tagname] == :property
             false
           else
-            f = m[:files][0]
-            Logger.warn(:enum, "Enums can only contain properties, #{m[:tagname]} found instead.", f[:filename], f[:linenr])
+            Logger.warn(:enum, "Enums can only contain properties, #{m[:tagname]} found instead.", m[:files][0])
             true
           end
         end
@@ -71,7 +70,7 @@ module JsDuck
       # values default to being public.
       def strip_inheritdoc(cls)
         cls[:members].each do |p|
-          p[:inheritdoc] = nil if p[:autodetected]
+          p[:inheritdoc] = nil if p[:autodetected] && p[:autodetected][:tagname]
         end
       end
 

data/lib/jsduck/process/ext4_events.rb

@@ -34,7 +34,8 @@ module JsDuck
         :tagname => :params,
         :name => "eOpts",
         :type => "Object",
-        :doc => "The options object passed to {@link Ext.util.Observable#addListener}."
+        :doc => "The options object passed to {@link Ext.util.Observable#addListener}.",
+        :ext4_auto_param => true,
       }
 
     end

data/lib/jsduck/process/global_members.rb

@@ -21,8 +21,7 @@ module JsDuck
         @classes_hash["global"][:members].each do |m|
           type = m[:tagname].to_s
           name = m[:name]
-          file = m[:files][0]
-          Logger.warn(:global, "Global #{type}: #{name}", file[:filename], file[:linenr])
+          Logger.warn(:global, "Global #{type}: #{name}", m[:files][0])
         end
 
         # Throw away the "global" class when --ignore-global option used

data/lib/jsduck/process/importer.rb

@@ -42,12 +42,8 @@ module JsDuck
       # creates index of all class members
       def members_id_index(json)
         index = {}
-        ["members", "statics"].each do |group_name|
-          json[group_name].each_pair do |tagname, members|
-            members.each do |m|
-              index[m["id"]] = true
-            end
-          end
+        json["members"].each do |m|
+          index[m["id"]] = true
         end
         index
       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

@@ -1,5 +1,7 @@
 require 'jsduck/logger'
 require 'jsduck/class'
+require 'jsduck/process/inherit_class'
+require 'jsduck/process/inherit_members'
 
 module JsDuck
   module Process
@@ -8,189 +10,18 @@ module JsDuck
     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|
-          resolve_class(cls) if cls[:inheritdoc]
-
-          new_cfgs = []
-          cls.all_local_members.each do |member|
-            if member[:inheritdoc]
-              resolve(member, new_cfgs)
-            end
-          end
-          move_cfgs(cls, new_cfgs) if new_cfgs.length > 0
-        end
-      end
-
-      private
-
-      # Copy over doc/params/return from parent member.
-      def resolve(m, new_cfgs)
-        parent = find_parent(m)
-
-        if m[:inheritdoc] && parent
-          m[:doc] = (m[:doc] + "\n\n" + parent[:doc]).strip
-          m[:params] = parent[:params] if parent[:params]
-          m[:return] = parent[:return] if parent[:return]
-          m[:type] = parent[:type] if parent[:type]
-
-          if m[:autodetected]
-            m[:deprecated] = parent[:deprecated] if parent[:deprecated] && !m[:deprecated]
-          end
-
-          # remember properties that have changed to configs
-          if m[:autodetected] && m[:tagname] != parent[:tagname]
-            new_cfgs << m
-          end
-        end
-
-        resolve_visibility(m, parent)
-      end
-
-      # Changes given properties into configs within class
-      def move_cfgs(cls, members)
-        members.each do |m|
-          m[:tagname] = :cfg
-        end
-        # Ask class to update its internal caches for these members
-        cls.update_members!(members)
-      end
-
-      # For auto-detected members/classes (which have @private == :inherit)
-      # Use the visibility from parent class (defaulting to private when no parent).
-      def resolve_visibility(m, parent)
-        if m[:autodetected] && !JsDuck::Class.constructor?(m)
-          if !parent || parent[:private]
-            m[:private] = true
-          end
-
-          m[:protected] = true if parent && parent[:protected]
-        end
-      end
-
-      # Finds parent member of the given member.  When @inheritdoc names
-      # a member to inherit from, finds that member instead.
-      #
-      # If the parent also has @inheritdoc, continues recursively.
-      def find_parent(m)
-
-        inherit = m[:inheritdoc] || {}
-        if inherit[:cls]
-          # @inheritdoc MyClass#member
-          parent_cls = @relations[m[:inheritdoc][:cls]]
-          return warn("class not found", m) unless parent_cls
-
-          parent = lookup_member(parent_cls, m)
-          return warn("member not found", m) unless parent
-
-        elsif inherit[:member]
-          # @inheritdoc #member
-          parent = lookup_member(@relations[m[:owner]], m)
-          return warn("member not found", m) unless parent
-
-        else
-          # @inheritdoc
-          parent_cls = @relations[m[:owner]].parent
-          mixins = @relations[m[:owner]].mixins
-
-          # Warn when no parent or mixins at all
-          if !parent_cls && mixins.length == 0
-            warn("parent class not found", m) unless m[:autodetected]
-            return nil
-          end
-
-          # First check for the member in all mixins, because members
-          # from mixins override those from parent class.  Looking first
-          # from mixins is probably a bit slower, but it's the correct
-          # order to do things.
-          if mixins.length > 0
-            parent = mixins.map {|mix| lookup_member(mix, m) }.compact.first
-          end
-
-          # When not found, try looking from parent class
-          if !parent && parent_cls
-            parent = lookup_member(parent_cls, m)
-          end
-
-          # Only when both parent and mixins fail, throw warning
-          if !parent
-            warn("parent member not found", m) unless m[:autodetected]
-            return nil
-          end
-        end
-
-        return parent[:inheritdoc] ? find_parent(parent) : parent
-      end
-
-      def lookup_member(cls, m)
-        inherit = m[:inheritdoc] || {}
-        name = inherit[:member] || m[:name]
-        tagname = inherit[:type] || m[:tagname]
-        static = inherit[:static] || m[:static]
-
-        if m[:autodetected]
-          # Auto-detected properties can override either a property or a
-          # config. So look for both types.
-          if tagname == :property
-            cfg = cls.find_members(:name => name, :tagname => :cfg, :static => static || false)[0]
-            prop = cls.find_members(:name => name, :tagname => :property, :static => static || false)[0]
-
-            if cfg && prop
-              prop
-            elsif cfg
-              cfg
-            elsif prop
-              prop
-            else
-              nil
-            end
-
-          else
-            # Unless the auto-detected member is detected as static,
-            # look only at instance members.
-            cls.find_members(:name => name, :tagname => tagname, :static => static || false)[0]
-          end
-        else
-          cls.find_members(:name => name, :tagname => tagname, :static => static)[0]
+          @inherit_class.resolve(cls)
+          @inherit_members.resolve(cls)
         end
       end
 
-      # Copy over doc from parent class.
-      def resolve_class(cls)
-        parent = find_class_parent(cls)
-
-        if parent
-          cls[:doc] = (cls[:doc] + "\n\n" + parent[:doc]).strip
-        end
-      end
-
-      def find_class_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[:inheritdoc] ? find_class_parent(parent) : parent
-      end
-
-      def warn(msg, item)
-        context = item[:files][0]
-        i_member = item[:inheritdoc][:member]
-
-        msg = "@inheritdoc #{item[:inheritdoc][:cls]}"+ (i_member ? "#" + i_member : "") + " - " + msg
-        Logger.warn(:inheritdoc, msg, context[:filename], context[:linenr])
-
-        return nil
-      end
-
     end
 
   end

data/lib/jsduck/process/inherit_members.rb

@@ -0,0 +1,257 @@
+require 'jsduck/logger'
+require 'jsduck/class'
+
+module JsDuck
+  module Process
+
+    # Deals with inheriting member documentation.
+    class InheritMembers
+      def initialize(relations)
+        @relations = relations
+      end
+
+      # Inherits docs for all members in class.
+      #
+      # In case of members with explicit @inheritdoc tags we inherit
+      # the following fields when they're not empty in current member:
+      #
+      # - :doc
+      # - :params
+      # - :return
+      # - :throws
+      #
+      # In case of auto-detected members that inherit from a public
+      # member in parent class, we inherit all fields that aren't
+      # present in current member, plus the :type field.
+      #
+      # Auto-detected members inheriting from other private
+      # auto-detected members follow the same rules of inheritance as
+      # members with explicit @inheritdoc.
+      #
+      # Additionally auto-detected properties get turned into configs
+      # when a public configs with same name is detected in parent
+      # class.
+      #
+      def resolve(cls)
+        new_cfgs = []
+
+        cls.all_local_members.each do |member|
+          if member[:inheritdoc]
+            resolve_member(cls, member, new_cfgs)
+          end
+        end
+
+        move_cfgs(cls, new_cfgs) if new_cfgs.length > 0
+      end
+
+      private
+
+      def resolve_member(cls, m, new_cfgs)
+        parent = find_parent(m)
+        if parent && parent[:inheritdoc]
+          resolve_parent(cls, parent)
+        end
+
+        if m[:inheritdoc] && parent
+          if autodetected?(m) && !parent[:private]
+            auto_inherit(m, parent)
+          else
+            inherit(m, parent)
+          end
+
+          # remember properties that have changed to configs
+          if autodetected?(m) && m[:tagname] != parent[:tagname]
+            new_cfgs << m
+          end
+        end
+
+        resolve_visibility(m, parent)
+
+        m[:inheritdoc] = nil
+      end
+
+      def resolve_parent(cls, parent)
+        new_cfgs = []
+        resolve_member(cls, parent, new_cfgs)
+        move_cfgs(cls, new_cfgs) if new_cfgs.length > 0
+      end
+
+      def inherit(m, parent)
+        m[:doc] = parent[:doc] if m[:doc].empty?
+
+        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
+
+        # Don't inherit type from parent when:
+        # - member itself has type and it's not auto-detected
+        # - or the type in parent is auto-detected.
+        unless m[:type] && m[:type] != "Object" && !auto?(m, :type) || auto?(parent, :type)
+          m[:type] = parent[:type]
+        end
+      end
+
+      def inherit_params?(m, parent)
+        # ignore the auto-inserted param of Ext4-style events
+        params = (m[:params] || []).reject {|p| p[:ext4_auto_param] }
+
+        if params.length > 0 && !auto?(m, :params)
+          # member itself has params and these are not auto-detected
+          false
+        elsif auto?(parent, :params)
+          # Params in parent are auto-detected.
+          false
+        else
+          true
+        end
+      end
+
+      def auto_inherit(m, parent)
+        m[:doc] = parent[:doc] if m[:doc].empty?
+
+        parent.each_pair do |key, value|
+          if key == :type || !m[key]
+            m[key] = value
+          end
+        end
+      end
+
+      # True when specific field of member has been auto-detected
+      def auto?(m, key)
+        m[:autodetected] && m[:autodetected][key]
+      end
+
+      # Changes given properties into configs within class
+      def move_cfgs(cls, members)
+        members.each do |m|
+          m[:tagname] = :cfg
+        end
+        # Ask class to update its internal caches for these members
+        cls.update_members!(members)
+      end
+
+      # For auto-detected members/classes (which have @private == :inherit)
+      # Use the visibility from parent class (defaulting to private when no parent).
+      def resolve_visibility(m, parent)
+        if autodetected?(m) && !JsDuck::Class.constructor?(m)
+          if !parent || parent[:private]
+            m[:private] = true
+          end
+
+          m[:protected] = true if parent && parent[:protected]
+        end
+      end
+
+      # Finds parent member of the given member.  When @inheritdoc names
+      # a member to inherit from, finds that member instead.
+      #
+      # If the parent also has @inheritdoc, continues recursively.
+      def find_parent(m)
+
+        inherit = m[:inheritdoc] || {}
+        if inherit[:cls]
+          # @inheritdoc MyClass#member
+          parent_cls = @relations[m[:inheritdoc][:cls]]
+          return warn("class not found", m) unless parent_cls
+
+          parent = lookup_member(parent_cls, m)
+          return warn("member not found", m) unless parent
+
+        elsif inherit[:member]
+          # @inheritdoc #member
+          parent = lookup_member(@relations[m[:owner]], m)
+          return warn("member not found", m) unless parent
+
+        else
+          # @inheritdoc
+          parent_cls = @relations[m[:owner]].parent
+          mixins = @relations[m[:owner]].mixins
+
+          # Warn when no parent or mixins at all
+          if !parent_cls && mixins.length == 0
+            warn("parent class not found", m) unless autodetected?(m)
+            return nil
+          end
+
+          # First check for the member in all mixins, because members
+          # from mixins override those from parent class.  Looking first
+          # from mixins is probably a bit slower, but it's the correct
+          # order to do things.
+          if mixins.length > 0
+            parent = mixins.map {|mix| lookup_member(mix, m) }.compact.first
+          end
+
+          # When not found, try looking from parent class
+          if !parent && parent_cls
+            parent = lookup_member(parent_cls, m)
+          end
+
+          # Only when both parent and mixins fail, throw warning
+          if !parent
+            warn("parent member not found", m) unless autodetected?(m)
+            return nil
+          end
+        end
+
+        return parent
+      end
+
+      def lookup_member(cls, m)
+        inherit = m[:inheritdoc] || {}
+        name = inherit[:member] || m[:name]
+        tagname = inherit[:type] || m[:tagname]
+        # When not explicitly inheriting from static member
+        # and the member itself is not static,
+        # inherit from instance member.
+        static = inherit[:static] || m[:static] || false
+
+        if autodetected?(m)
+          # Auto-detected properties can override either a property or a
+          # config. So look for both types.
+          if tagname == :property
+            cfg = cls.find_members(:name => name, :tagname => :cfg, :static => static)[0]
+            prop = cls.find_members(:name => name, :tagname => :property, :static => static)[0]
+
+            if cfg && prop
+              prop
+            elsif cfg
+              cfg
+            elsif prop
+              prop
+            else
+              nil
+            end
+
+          else
+            cls.find_members(:name => name, :tagname => tagname, :static => static)[0]
+          end
+        else
+          m = cls.find_members(:name => name, :tagname => tagname, :static => static)[0]
+          # When member was not found with explicit staticality and
+          # the @inheritdoc tag contained no explicit "static", then
+          # look for both static and instance members.
+          if !m && !inherit[:static]
+            m = cls.find_members(:name => name, :tagname => tagname, :static => nil)[0]
+          end
+          m
+        end
+      end
+
+      # True when the entire member was auto-detected
+      def autodetected?(m)
+        m[:autodetected] && m[:autodetected][:tagname]
+      end
+
+      def warn(msg, m)
+        inh_member = m[:inheritdoc][:member]
+        inh_target = (m[:inheritdoc][:cls] || "") + (inh_member ? "#" + inh_member : "")
+
+        Logger.warn(:inheritdoc, "@inheritdoc #{inh_target} - #{msg}", m[:files][0])
+
+        return nil
+      end
+
+    end
+
+  end
+end