jsduck 4.10.4 → 5.0.0.beta01

data/lib/jsduck/process/importer.rb

@@ -0,0 +1,58 @@
+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
+        Util::NullObject.new(:[] => Util::NullObject.new(:[] => true))
+      end
+
+      # Reads in data from all .json files in directory
+      def read(ver)
+        # Map list of files into pairs of (classname, members-hash)
+        pairs = Util::Parallel.map(Dir[ver[:path] + "/*.json"]) do |filename|
+          JsDuck::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
+
+      # 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
+        end
+        index
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/process/inherit_doc.rb

@@ -0,0 +1,197 @@
+require 'jsduck/logger'
+require 'jsduck/class'
+
+module JsDuck
+  module Process
+
+    # Deals with inheriting documentation
+    class InheritDoc
+      def initialize(relations)
+        @relations = 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]
+        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
+end

data/lib/jsduck/process/lint.rb

@@ -0,0 +1,135 @@
+require 'jsduck/logger'
+require 'jsduck/class'
+
+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_no_doc
+        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
+          (member[:params] || []).each do |p|
+            if !p[:name] || p[:name] == ""
+              warn(:name_missing, "Unnamed parameter", member)
+            end
+          end
+        end
+      end
+
+      # print warning for each class or public member with no name
+      def warn_no_doc
+        @relations.each do |cls|
+          if cls[:doc] == ""
+            warn(:no_doc, "No documentation for #{cls[:name]}", cls)
+          end
+        end
+        each_member do |member|
+          if member[:doc] == "" && !member[:private] && !member[:hide] && !JsDuck::Class.constructor?(member)
+            warn(:no_doc, "No documentation for #{member[:owner]}##{member[:name]}", member)
+          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
+            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 = {}
+          (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)
+        context = member[:files][0]
+        Logger.warn(type, msg, context[:filename], context[:linenr])
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/process/overrides.rb

@@ -0,0 +1,99 @@
+require 'jsduck/logger'
+
+module JsDuck
+  module Process
+
+    class Overrides
+      def initialize(classes_hash, opts = {:external_classes => []})
+        @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_classes] += overrides.map {|c| c[:name] }
+      end
+
+      private
+
+      # Applies override class to target class
+      def process(override)
+        target = @classes_hash[override[:override]]
+        unless target
+          ctx = override[:files][0]
+          return Logger.warn(:extend, "Class #{override[:override]} not found", ctx[:filename], ctx[:linenr])
+        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