jsduck 4.10.4 → 5.0.0.beta01

data/lib/jsduck/auto_categories.rb

@@ -1,80 +0,0 @@
-module JsDuck
-
-  # Automatically divides all available classes into categories
-  class AutoCategories
-    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

data/lib/jsduck/batch_formatter.rb

@@ -1,60 +0,0 @@
-require 'jsduck/util/parallel'
-require 'jsduck/class_formatter'
-require 'jsduck/doc_formatter'
-require 'jsduck/img/dir_set'
-require 'jsduck/logger'
-
-module JsDuck
-
-  # Performs the formatting of the doc-object of all classes.
-  class BatchFormatter
-
-    # Formats all classes.
-    # Also registers found images in assets.
-    def self.format_all!(relations, assets, opts)
-      # Format all doc-objects in parallel
-      formatted_classes = Util::Parallel.map(relations.classes) do |cls|
-
-        files = cls[:files].map {|f| f[:filename] }.join(" ")
-        Logger.log("Markdown formatting #{cls[:name]}", files)
-
-        formatter = create_class_formatter(relations, opts)
-        begin
-          {
-            :doc => formatter.format(cls.internal_doc),
-            :images => formatter.images.all_used
-          }
-        rescue
-          Logger.fatal_backtrace("Error while formatting #{cls[:name]} #{files}", $!)
-          exit(1)
-        end
-      end
-
-      # Then merge the data back to classes sequentially
-      formatted_classes.each do |cls|
-        relations[cls[:doc][:name]].internal_doc = cls[:doc]
-        # Perform lookup of all the images again.  We're really doing
-        # this work twice now, but as we usually don't have excessive
-        # amounts of images, the performance penalty should be minimal.
-        cls[:images].each {|img| assets.images.get(img[:filename]) }
-      end
-
-      # Print warnings for unused images
-      assets.images.report_unused
-    end
-
-    # Factory method to create new ClassFormatter instances.
-    def self.create_class_formatter(relations, opts)
-      doc_formatter = DocFormatter.new(relations, opts)
-      doc_formatter.images = Img::DirSet.new(opts.images, "images")
-
-      class_formatter = ClassFormatter.new(relations, doc_formatter)
-      # Don't format types when exporting
-      class_formatter.include_types = !opts.export
-
-      class_formatter
-    end
-
-  end
-
-end

data/lib/jsduck/categories.rb

@@ -1,73 +0,0 @@
-require 'jsduck/logger'
-require 'jsduck/file_categories'
-require 'jsduck/auto_categories'
-require 'jsduck/categories_class_name'
-require 'jsduck/columns'
-
-module JsDuck
-
-  # Reads in categories and outputs them as HTML div
-  class Categories
-    def self.create(filename, doc_formatter, relations)
-      if filename
-        categories = FileCategories.new(filename, relations)
-      else
-        categories = AutoCategories.new(relations)
-      end
-      Categories.new(categories.generate, doc_formatter, relations)
-    end
-
-    def initialize(categories, doc_formatter, relations={})
-      @categories = categories
-      @class_name = CategoriesClassName.new(doc_formatter, relations)
-      @columns = Columns.new("classes")
-    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
-
-    private
-
-    def render_columns(groups)
-      align = ["left-column", "middle-column", "right-column"]
-      i = -1
-      return @columns.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
-
-  end
-
-end

data/lib/jsduck/categories_class_name.rb

@@ -1,37 +0,0 @@
-module JsDuck
-
-  # Renders class names for class categories page.
-  class CategoriesClassName
-    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[:meta][:new]
-        "&nbsp;<span class='new-class' title='New class'>&#9733;</span>"
-      else
-        ""
-      end
-    end
-
-  end
-
-end

data/lib/jsduck/circular_deps.rb

@@ -1,56 +0,0 @@
-require 'jsduck/logger'
-
-module JsDuck
-
-  # Checks for circular dependencies
-  class CircularDeps
-    def initialize(classes)
-      @classes = classes
-    end
-
-    # Checks all classes for circular dependencies.
-    #
-    # When found, exits with a fatal error message.
-    def check_all
-      @classes.each do |cls|
-        if chain = check(cls)
-          Logger.fatal("Class #{cls[:name]} has a circular dependency: #{chain}")
-          exit 1
-        end
-      end
-    end
-
-    # Checks class for circular dependencies.
-    #
-    # When all OK, returns false.
-    #
-    # When circular dependencies found returns a string describing the
-    # problematic dependency chain e.g. "Foo extends Bar mixins Foo".
-    def check(cls, names = [])
-      names += [cls[:name]]
-
-      if cls.parent && chain = track_circular(" extends ", cls.parent, names)
-        return chain
-      end
-
-      cls.mixins.each do |mixin|
-        if chain = track_circular(" mixins ", mixin, names)
-          return chain
-        end
-      end
-
-      false
-    end
-
-    def track_circular(type, cls, names)
-      names += [type]
-      if names.include?(cls[:name])
-        (names + [cls[:name]]).join("")
-      else
-        check(cls, names)
-      end
-    end
-
-  end
-
-end

data/lib/jsduck/class_formatter.rb

@@ -1,102 +0,0 @@
-require 'jsduck/type_parser'
-require 'jsduck/logger'
-require 'jsduck/meta_tag_registry'
-require 'jsduck/shortener'
-require 'jsduck/util/html'
-
-module JsDuck
-
-  # Converts :doc properties of class from markdown to HTML, resolves
-  # @links, and converts type definitions to HTML.
-  class ClassFormatter
-    # Set to false to disable HTML-formatting of type definitions.
-    attr_accessor :include_types
-
-    def initialize(relations, formatter)
-      @relations = relations
-      @formatter = formatter
-      # inject formatter to all meta-tags
-      MetaTagRegistry.instance.formatter = formatter
-      @include_types = true
-    end
-
-    # Runs the formatter on doc object of a class.
-    # Accessed using Class#internal_doc
-    def format(cls)
-      @cls = cls
-      @formatter.class_context = cls[:name]
-      @formatter.doc_context = cls[:files][0]
-      cls[:doc] = @formatter.format(cls[:doc]) if cls[:doc]
-      # format all members (except hidden ones)
-      cls[:members] = cls[:members].map {|m| m[:meta][:hide] ? m : format_member(m)  }
-      cls[:html_meta] = format_meta_data(cls)
-      cls
-    end
-
-    # Access to the Img::DirSet object inside doc-formatter
-    def images
-      @formatter.images
-    end
-
-    private
-
-    def format_member(m)
-      @formatter.doc_context = m[:files][0]
-      m[:doc] = @formatter.format(m[:doc]) if m[:doc]
-      if expandable?(m) || Shortener.too_long?(m[:doc])
-        m[:shortDoc] = Shortener.shorten(m[:doc])
-      end
-
-      # We don't validate and format CSS var and mixin type definitions
-      is_css_tag = m[:tagname] == :css_var || m[:tagname] == :css_mixin
-
-      m[:html_type] = (@include_types && !is_css_tag) ? format_type(m[:type]) : m[:type] if m[:type]
-      m[:params] = m[:params].map {|p| format_item(p, is_css_tag) } if m[:params]
-      m[:return] = format_item(m[:return], is_css_tag) if m[:return]
-      m[:throws] = m[:throws].map {|t| format_item(t, is_css_tag) } if m[:throws]
-      m[:properties] = m[:properties].map {|b| format_item(b, is_css_tag) } if m[:properties]
-      m[:html_meta] = format_meta_data(m)
-      m
-    end
-
-    def expandable?(m)
-      m[:params] || (m[:properties] && m[:properties].length > 0) || m[:default] || m[:meta][:deprecated] || m[:meta][:template]
-    end
-
-    def format_item(it, is_css_tag)
-      it[:doc] = @formatter.format(it[:doc]) if it[:doc]
-      it[:html_type] = (@include_types && !is_css_tag) ? format_type(it[:type]) : it[:type] if it[:type]
-      it[:properties] = it[:properties].map {|s| format_item(s, is_css_tag) } if it[:properties]
-      it
-    end
-
-    def format_type(type)
-      tp = TypeParser.new(@relations, @formatter)
-      if tp.parse(type)
-        tp.out
-      else
-        context = @formatter.doc_context
-        if tp.error == :syntax
-          Logger.warn(:type_syntax, "Incorrect type syntax #{type}", context[:filename], context[:linenr])
-        else
-          Logger.warn(:type_name, "Unknown type #{type}", context[:filename], context[:linenr])
-        end
-        Util::HTML.escape(type)
-      end
-    end
-
-    def format_meta_data(context)
-      result = {}
-      context[:meta].each_pair do |key, value|
-        if value
-          tag = MetaTagRegistry.instance[key]
-          tag.context = context
-          result[key] = tag.to_html(value)
-        end
-      end
-      result
-    end
-
-  end
-
-end

data/lib/jsduck/columns.rb

@@ -1,56 +0,0 @@
-module JsDuck
-
-  # Splits array of items with subitems into roughly equal size groups.
-  class Columns
-    # Initialized with the name of subitems field.
-    def initialize(subitems_field)
-      @header_size = 3
-      @subitems_field = subitems_field
-    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
-
-    private
-
-    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)
-      arr.reduce(0) {|sum, item| sum + item[@subitems_field].length + @header_size }
-    end
-
-  end
-
-end