jsduck 4.10.4 → 5.0.0.beta01

data/lib/jsduck/assets.rb

@@ -4,9 +4,8 @@ require 'jsduck/welcome'
 require 'jsduck/guides'
 require 'jsduck/videos'
 require 'jsduck/examples'
-require 'jsduck/categories'
-require 'jsduck/doc_formatter'
-require 'jsduck/news'
+require 'jsduck/categories/factory'
+require 'jsduck/format/doc'
 
 module JsDuck
 
@@ -23,21 +22,19 @@ module JsDuck
     attr_reader :videos
     attr_reader :examples
     attr_reader :categories
-    attr_reader :news
 
     def initialize(relations, opts)
       @relations = relations
       @opts = opts
 
-      doc_formatter = DocFormatter.new(@relations, @opts)
+      doc_formatter = Format::Doc.new(@relations, @opts)
 
       @images = Img::DirSet.new(@opts.images, "images")
       @welcome = Welcome.create(@opts.welcome, doc_formatter)
       @guides = Guides.create(@opts.guides, doc_formatter, @opts)
       @videos = Videos.create(@opts.videos)
       @examples = Examples.create(@opts.examples, @opts)
-      @categories = Categories.create(@opts.categories_path, doc_formatter, @relations)
-      @news = News.create(@relations, doc_formatter, @opts)
+      @categories = Categories::Factory.create(@opts.categories_path, doc_formatter, @relations)
     end
 
     # Writes out the assets that can be written out separately:

data/lib/jsduck/base_type.rb

@@ -0,0 +1,53 @@
+require 'jsduck/tag_registry'
+
+module JsDuck
+
+  # Detects the type of documentation object: class, method, cfg, etc
+  class BaseType
+    # Given parsed documentation and code, returns the tagname for
+    # documentation item.
+    #
+    # @param doc_map Result from DocParser turned into hash of tags.
+    # @param code Result from Ast#detect or CssParser#parse
+    # @returns :class or any of the member type symbols (:method, :event, ...).
+    #
+    def self.detect(doc_map, code)
+      if doc_map[:class] || doc_map[:override]
+        :class
+      elsif type = detect_member(doc_map)
+        type
+      elsif doc_map[:type]
+        # @type also results in property
+        :property
+      elsif code[:tagname] == :class
+        :class
+      elsif code[:tagname] == :css_mixin
+        :css_mixin
+      elsif doc_map[:cfg]
+        :cfg
+      elsif doc_map[:constructor]
+        :method
+      elsif doc_map[:params] || doc_map[:return]
+        :method
+      else
+        code[:tagname]
+      end
+    end
+
+    # Detects any of the members defined using a Tag class.
+    # Returns the detected member type on success.
+    # Otherwise nil.
+    def self.detect_member(doc_map)
+      type = TagRegistry.member_type_names.find {|type| doc_map[type] }
+
+      if type == :cfg
+        # Only detect a single @cfg as a :cfg.
+        # Multiple ones can be part of a class.
+        return (doc_map[:cfg].length == 1) ? :cfg : nil
+      else
+        type
+      end
+    end
+  end
+
+end

data/lib/jsduck/batch_parser.rb

@@ -1,46 +1,22 @@
 require 'jsduck/util/parallel'
 require 'jsduck/util/io'
+require 'jsduck/parser'
 require 'jsduck/source/file'
-require 'jsduck/aggregator'
-require 'jsduck/class'
-require 'jsduck/relations'
 require 'jsduck/logger'
-require 'jsduck/inherit_doc'
-require 'jsduck/importer'
-require 'jsduck/return_values'
-require 'jsduck/lint'
-require 'jsduck/circular_deps'
 
 module JsDuck
 
-  # Performs the parsing of all input files.  Input files are read
-  # from options object (originating from command line).
+  # Parses of all input files.  Input files are read from options
+  # object (originating from command line).
   class BatchParser
-    def initialize(opts)
-      @opts = opts
-    end
-
-    # Array of Source::File objects.
-    # Available after calling the #run method.
-    attr_reader :parsed_files
-
-    # Parses the files and returns instance of Relations class.
-    def run
-      @parsed_files = parallel_parse(@opts.input_files)
-      result = aggregate(@parsed_files)
-      @relations = filter_classes(result)
-      apply_extra_processing
-      return @relations
-    end
 
-    private
-
-    # Parses the files in parallel using as many processes as available CPU-s
-    def parallel_parse(filenames)
-      Util::Parallel.map(filenames) do |fname|
+    def self.parse(opts)
+      Util::Parallel.map(opts.input_files) do |fname|
         Logger.log("Parsing", fname)
         begin
-          Source::File.new(Util::IO.read(fname), fname, @opts)
+          source = Util::IO.read(fname)
+          docs = Parser.new.parse(source, fname, opts)
+          Source::File.new(source, docs, fname)
         rescue
           Logger.fatal_backtrace("Error while parsing #{fname}", $!)
           exit(1)
@@ -48,61 +24,6 @@ module JsDuck
       end
     end
 
-    # Aggregates parsing results sequencially
-    def aggregate(parsed_files)
-      agr = Aggregator.new
-      parsed_files.each do |file|
-        Logger.log("Aggregating", file.filename)
-        agr.aggregate(file)
-      end
-      agr.classify_orphans
-      agr.create_global_class
-      agr.remove_ignored_classes
-      agr.create_accessors
-      if @opts.ext4_events == true || (@opts.ext4_events == nil && agr.ext4?)
-        agr.append_ext4_event_options
-      end
-      agr.process_enums
-      # Ignore override classes after applying them to actual classes
-      @opts.external_classes += agr.process_overrides.map {|o| o[:name] }
-      agr.result
-    end
-
-    # Turns all aggregated data into Class objects.
-    # Depending on --ignore-global either keeps or discards the global class.
-    # Warnings for global members are printed regardless of that setting,
-    # but of course can be turned off using --warnings=-global
-    def filter_classes(docs)
-      classes = []
-      docs.each do |d|
-        cls = Class.new(d)
-        if d[:name] != "global"
-          classes << cls
-        else
-          # add global class only if --ignore-global not specified
-          classes << cls unless @opts.ignore_global
-
-          # Print warning for each global member
-          cls.all_local_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])
-          end
-        end
-      end
-      Relations.new(classes, @opts.external_classes)
-    end
-
-    # Do all kinds of post-processing on relations.
-    def apply_extra_processing
-      CircularDeps.new(@relations).check_all
-      InheritDoc.new(@relations).resolve_all
-      Importer.import(@opts.imports, @relations, @opts.new_since)
-      ReturnValues.auto_detect(@relations)
-      Lint.new(@relations).run
-    end
-
   end
 
 end

data/lib/jsduck/batch_processor.rb

@@ -0,0 +1,77 @@
+require 'jsduck/aggregator'
+require 'jsduck/class'
+require 'jsduck/relations'
+require 'jsduck/logger'
+require 'jsduck/util/singleton'
+require 'jsduck/process/ignored_classes'
+require 'jsduck/process/global_members'
+require 'jsduck/process/enums'
+require 'jsduck/process/accessors'
+require 'jsduck/process/ext4_events'
+require 'jsduck/process/overrides'
+require 'jsduck/process/inherit_doc'
+require 'jsduck/process/versions'
+require 'jsduck/process/return_values'
+require 'jsduck/process/lint'
+require 'jsduck/process/circular_deps'
+
+module JsDuck
+
+  # Processes the parsing results into Relations object.
+  class BatchProcessor
+    include Util::Singleton
+
+    # Processes array of Source::File objects from BatchParser and
+    # returns instance of Relations class.
+    def process(parsed_files, opts)
+      r = aggregate(parsed_files)
+      r = pre_process(r, opts)
+      r = to_class_objects(r, opts)
+      return post_process(r, opts)
+    end
+
+    private
+
+    # Aggregates parsing results sequencially
+    def aggregate(parsed_files)
+      agr = Aggregator.new
+      parsed_files.each do |file|
+        Logger.log("Aggregating", file.filename)
+        agr.aggregate(file)
+      end
+      agr.result
+    end
+
+    # Do all kinds of processing on the classes hash before turning it
+    # into Relations object.
+    def pre_process(classes_hash, opts)
+      Process::IgnoredClasses.new(classes_hash).process_all!
+      Process::GlobalMembers.new(classes_hash, opts).process_all!
+      Process::Accessors.new(classes_hash).process_all!
+      Process::Ext4Events.new(classes_hash, opts).process_all!
+      Process::Enums.new(classes_hash).process_all!
+      Process::Overrides.new(classes_hash, opts).process_all!
+
+      classes_hash.values
+    end
+
+    # Turns all aggregated data into Class objects and places the
+    # classes inside Relations container.
+    def to_class_objects(docs, opts)
+      classes = docs.map {|d| Class.new(d) }
+      Relations.new(classes, opts.external_classes)
+    end
+
+    # Do all kinds of post-processing on Relations object.
+    def post_process(relations, opts)
+      Process::CircularDeps.new(relations).process_all!
+      Process::InheritDoc.new(relations).process_all!
+      Process::Versions.new(relations, opts).process_all!
+      Process::ReturnValues.new(relations).process_all!
+      Process::Lint.new(relations).process_all!
+      relations
+    end
+
+  end
+
+end

data/lib/jsduck/categories/auto.rb

@@ -0,0 +1,83 @@
+module JsDuck
+  module Categories
+
+    # Automatically divides all available classes into categories
+    class Auto
+      def initialize(relations)
+        @relations = relations
+      end
+
+      # Performs the generation
+      def generate
+        # list names of all public classes
+        class_names = @relations.to_a.find_all {|cls| !cls[:private] }.map {|cls| cls[:name] }
+
+        # divide classes into top-level categories by namespace
+        categories = categorize(class_names)
+
+        # in each category, create sub-categories
+        categories.each_pair do |ns, classes|
+          categories[ns] = categorize(classes, 1)
+        end
+
+        # Turn categories hash into array, sort everything
+        categories_array = []
+        categories.each_pair do |ns, groups|
+          groups_array = []
+          groups.each_pair do |gns, classes|
+            groups_array << {
+              "name" => gns,
+              "classes" => classes.sort
+            }
+          end
+          groups_array.sort! {|a, b| cat_compare(a, b) }
+          categories_array << {
+            "name" => ns,
+            "groups" => groups_array
+          }
+        end
+        categories_array.sort! {|a, b| cat_compare(a, b) }
+
+        return categories_array
+      end
+
+      # Divides classes into categories by namespace.  Collapses
+      # categories having only one class into a category "Others..."
+      def categorize(class_names, level=0)
+        categories = {}
+        class_names.each do |name|
+          ns = name.split(/\./)[level] || name.split(/\./)[0]
+          categories[ns] = [] unless categories[ns]
+          categories[ns] << name
+        end
+
+        globals = []
+        categories.each_pair do |ns, classes|
+          if classes.length == 1
+            globals << classes[0]
+            categories.delete(ns)
+          end
+        end
+        if globals.length > 0
+          categories["Others..."] = globals
+        end
+
+        categories
+      end
+
+      # Comparison function for sorting categories that always places
+      # "Others..." category at the end.
+      def cat_compare(a, b)
+        if a["name"] == "Others..."
+          1
+        elsif b["name"] == "Others..."
+          -1
+        else
+          a["name"] <=> b["name"]
+        end
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/categories/class_name.rb

@@ -0,0 +1,63 @@
+module JsDuck
+  module Categories
+
+    # Renders class names for class categories page.
+    class ClassName
+      def initialize(doc_formatter, relations={})
+        @doc_formatter = doc_formatter
+        @relations = relations
+      end
+
+      # Renders the class name as a link or plain text.
+      #
+      # For new classes appends a star behind class name.  For classes
+      # with new members appends list n small stars behind class name
+      # (reflecting the number of new members).
+      def render(name)
+        cls = @relations[name]
+        if cls
+          @doc_formatter.link(name, nil, name) + render_new_label(cls)
+        else
+          name
+        end
+      end
+
+      private
+
+      # Adds small star to new classes in the current version.
+      def render_new_label(cls)
+        if cls[:new]
+          "&nbsp;<span class='new-class' title='New class'>#{stars(1)}</span>"
+        else
+          n = new_members_count(cls)
+          if n > 0
+            title = "#{n} new member#{(n>1) ? 's' : ''}"
+            "&nbsp;<span class='new-members' title='#{title}'>#{stars(n)}</span>"
+          else
+            ""
+          end
+        end
+      end
+
+      # Produces string of n stars.
+      # First 3 stars are rendered as "<unicode-star>", the following as "+".
+      # At max 15 stars are rendered.
+      def stars(n)
+        if n > 15
+          stars(3) + ("+" * (15-3))
+        elsif n > 3
+          stars(3) + ("+" * (n-3))
+        else
+          "&#9733;" * n
+        end
+      end
+
+      # Returns number of new members the class has in the current version
+      def new_members_count(cls)
+        cls.find_members(:local => true).find_all {|m| m[:new] && !m[:private] }.length
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/categories/factory.rb

@@ -0,0 +1,113 @@
+require 'jsduck/logger'
+require 'jsduck/categories/file'
+require 'jsduck/categories/auto'
+require 'jsduck/categories/class_name'
+
+module JsDuck
+  module Categories
+
+    # Reads in categories and outputs them as HTML div
+    class Factory
+      def self.create(filename, doc_formatter, relations)
+        if filename
+          categories = Categories::File.new(filename, relations)
+        else
+          categories = Categories::Auto.new(relations)
+        end
+        Categories::Factory.new(categories.generate, doc_formatter, relations)
+      end
+
+      def initialize(categories, doc_formatter, relations={})
+        @categories = categories
+        @class_name = Categories::ClassName.new(doc_formatter, relations)
+      end
+
+      # Returns HTML listing of classes divided into categories
+      def to_html(style="")
+        html = @categories.map do |category|
+          [
+            "<div class='section'>",
+            "<h1>#{category['name']}</h1>",
+            render_columns(category['groups']),
+            "<div style='clear:both'></div>",
+            "</div>",
+          ]
+        end.flatten.join("\n")
+
+        return <<-EOHTML
+          <div id='categories-content' style='#{style}'>
+            #{html}
+          </div>
+        EOHTML
+      end
+
+      def render_columns(groups)
+        align = ["left-column", "middle-column", "right-column"]
+        i = -1
+        return split(groups, 3).map do |col|
+          i += 1
+          [
+            "<div class='#{align[i]}'>",
+            render_groups(col),
+            "</div>",
+          ]
+        end
+      end
+
+      def render_groups(groups)
+        return groups.map do |g|
+          [
+            "<h3>#{g['name']}</h3>",
+            "<ul class='links'>",
+            g["classes"].map {|cls| "<li>" + @class_name.render(cls) + "</li>" },
+            "</ul>",
+          ]
+        end
+      end
+
+      # Splits the array of items into n chunks so that the sum of
+      # largest chunk is as small as possible.
+      #
+      # This is a brute-force implementation - we just try all the
+      # combinations and choose the best one.
+      def split(items, n)
+        if n == 1
+          [items]
+        elsif items.length <= n
+          Array.new(n) {|i| items[i] ? [items[i]] : [] }
+        else
+          min_max = nil
+          min_arr = nil
+          i = 0
+          while i <= items.length-n
+            i += 1
+            # Try placing 1, 2, 3, ... items to first chunk.
+            # Calculate the remaining chunks recursively.
+            cols = [items[0,i]] + split(items[i, items.length], n-1)
+            max = max_sum(cols)
+            # Is this the optimal solution so far? Remember it.
+            if !min_max || max < min_max
+              min_max = max
+              min_arr = cols
+            end
+          end
+          min_arr
+        end
+      end
+
+      def max_sum(cols)
+        cols.map {|col| sum(col) }.max
+      end
+
+      # Finds the total size of items in array
+      #
+      # The size of one item is it's number of classes + the space for header
+      def sum(arr)
+        header_size = 3
+        arr.reduce(0) {|sum, item| sum + item["classes"].length + header_size }
+      end
+
+    end
+
+  end
+end