solvas-jsduck 6.0.0.beta.1888

data/lib/jsduck/process/inherit_members.rb

@@ -0,0 +1,259 @@
+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
+      # - :properties
+      #
+      # 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
+        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
+        # - 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 == :overrides
+            # overrides can't be inherited.
+          elsif 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
+      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

data/lib/jsduck/process/lint.rb

@@ -0,0 +1,118 @@
+require 'jsduck/logger'
+
+module JsDuck
+  module Process
+
+    # Reports bugs and problems in documentation
+    class Lint
+      attr_accessor :relations
+
+      def initialize(relations)
+        @relations = relations
+      end
+
+      # Runs the linter
+      def process_all!
+        warn_unnamed
+        warn_optional_params
+        warn_duplicate_params
+        warn_duplicate_members
+        warn_singleton_statics
+        warn_empty_enums
+      end
+
+      # print warning for each member or parameter with no name
+      def warn_unnamed
+        each_member do |member|
+          if !member[:name] || member[:name] == ""
+            warn(:name_missing, "Unnamed #{member[:tagname]}", member)
+          end
+          Array(member[:params]).each do |p|
+            if !p[:name] || p[:name] == ""
+              warn(:name_missing, "Unnamed parameter", member)
+            end
+          end
+        end
+      end
+
+      # print warning for each non-optional parameter that follows an optional parameter
+      def warn_optional_params
+        each_member do |member|
+          if member[:tagname] == :method
+            optional_found = false
+            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
+              optional_found = optional_found || p[:optional]
+            end
+          end
+        end
+      end
+
+      # print warnings for duplicate parameter names
+      def warn_duplicate_params
+        each_member do |member|
+          params = {}
+          Array(member[:params]).each do |p|
+            if params[p[:name]]
+              warn(:dup_param, "Duplicate parameter name #{p[:name]}", member)
+            end
+            params[p[:name]] = true
+          end
+        end
+      end
+
+      # print warnings for duplicate member names
+      def warn_duplicate_members
+        @relations.each do |cls|
+          members = {:members => {}, :statics => {}}
+          cls.all_local_members.each do |m|
+            group = m[:static] ? :statics : :members
+            type = m[:tagname]
+            name = m[:name]
+            hash = members[group][type] || {}
+            if hash[name]
+              warn(:dup_member, "Duplicate #{type} name #{name}", hash[name])
+              warn(:dup_member, "Duplicate #{type} name #{name}", m)
+            end
+            hash[name] = m
+            members[group][type] = hash
+          end
+        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].length == 0
+            warn(:enum, "Enum #{cls[:name]} defined without values in it", cls)
+          end
+        end
+      end
+
+      # Loops through all members of all classes
+      def each_member(&block)
+        @relations.each {|cls| cls.all_local_members.each(&block) }
+      end
+
+      # Prints warning + filename and linenumber from doc-context
+      def warn(type, msg, member)
+        Logger.warn(type, msg, member[:files][0])
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/process/no_doc.rb

@@ -0,0 +1,50 @@
+require 'jsduck/logger'
+require 'jsduck/class'
+
+module JsDuck
+  module Process
+
+    # Reports missing documentation
+    class NoDoc
+      def initialize(relations)
+        @relations = relations
+      end
+
+      # Prints warning for each class or public member with no name
+      def process_all!
+        @relations.each do |cls|
+
+          if cls[:doc] == ""
+            warn(:class, "No documentation for #{cls[:name]}", cls)
+          end
+
+          cls.all_local_members.each do |member|
+            if !member[:hide] && !JsDuck::Class.constructor?(member)
+              if member[:doc] == ""
+                warn(:member, "No documentation for #{member[:owner]}##{member[:name]}", member)
+              end
+
+              (member[:params] || []).each do |p|
+                if p[:doc] == ""
+                  warn(:param, "No documentation for parameter #{p[:name]} of #{member[:owner]}##{member[:name]}", member)
+                end
+              end
+
+            end
+          end
+
+        end
+      end
+
+      private
+
+      def warn(type, msg, owner)
+        visibility = owner[:private] ? :private : (owner[:protected] ? :protected : :public)
+
+        Logger.warn(:nodoc, msg, owner[:files][0], [type, visibility])
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/process/overrides.rb

@@ -0,0 +1,99 @@
+require 'jsduck/logger'
+require 'ostruct'
+
+module JsDuck
+  module Process
+
+    class Overrides
+      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
+      # options object.
+      def process_all!
+        overrides = []
+
+        @classes_hash.each_value do |cls|
+          if cls[:override]
+            process(cls)
+            overrides << cls
+          end
+        end
+
+        # discard each override class
+        overrides.each do |cls|
+          @classes_hash.delete(cls[:name])
+        end
+
+        @opts.external += overrides.map {|c| c[:name] }
+      end
+
+      private
+
+      # Applies override class to target class
+      def process(override)
+        target = @classes_hash[override[:override]]
+        unless target
+          return Logger.warn(:extend, "Class #{override[:override]} not found", override[:files][0])
+        end
+
+        # Combine comments of classes
+        if override[:doc].length > 0
+          add_doc(target, "**From override #{get_name(override)}:** " + override[:doc])
+        end
+        target[:files] += override[:files]
+
+        # Build lookup table of existing members
+        existing = {}
+        each_member(target) do |m|
+          existing[m[:id]] = m
+        end
+
+        # When the same member exists in overridden class, just append
+        # the docs.  Otherwise add the member as a whole to the class.
+        each_member(override) do |m|
+          ex = existing[m[:id]]
+          if ex
+            if m[:doc].length > 0
+              add_doc(ex, "**From override #{get_name(override)}:** " + m[:doc])
+            else
+              add_doc(ex, "**Overridden in #{get_name(override)}.**")
+            end
+            ex[:files] += m[:files]
+          else
+            add_member(target, m)
+            add_doc(m, "**Defined in override #{get_name(override)}.**")
+            m[:owner] = target[:name]
+          end
+        end
+      end
+
+      # helpers
+
+      def get_name(override)
+        if override[:name] != ""
+          override[:name]
+        else
+          override[:files][0][:filename]
+        end
+      end
+
+      def each_member(cls)
+        cls[:members].each {|m| yield m }
+      end
+
+      def add_member(cls, m)
+        cls[:members] << m
+      end
+
+      def add_doc(m, doc)
+        m[:doc] = (m[:doc] + "\n\n" + doc).strip
+      end
+    end
+
+  end
+end