jsduck 4.10.4 → 5.0.0.beta01

data/lib/jsduck/meta_tag_registry.rb

@@ -1,111 +0,0 @@
-require "jsduck/meta_tag_loader"
-
-module JsDuck
-
-  # Access to meta-tags
-  class MetaTagRegistry
-
-    @@instance = nil
-
-    # Returns singleton instance of MetaTagRegistry.
-    # By default this will be auto-loaded with builtin tags.
-    def self.instance
-      if !@@instance
-        @@instance = MetaTagRegistry.new
-        @@instance.load([:builtins])
-      end
-      @@instance
-    end
-
-    # Allows injecting another MetaTagRegistry to be used as a global instance.
-    def self.instance=(instance)
-      @@instance = instance
-    end
-
-
-    def initialize
-      @tags = []
-      @map = {}
-    end
-
-    # Loads meta-tags from the given paths.  See MetaTagLoader#load
-    # for details.
-    #
-    # This should only be called once. Calling it twice will override
-    # the previously loaded tags.
-    def load(paths)
-      loader = MetaTagLoader.new
-      paths.each {|p| loader.load(p) }
-      register(loader.meta_tags)
-    end
-
-    # Registers MetaTag instances.
-    #
-    # NB! This is for testing purposes only, elsewhere always use #load.
-    def register(tags)
-      @tags = tags
-      register_keys
-    end
-
-    # Returns array of all available tag instances.
-    # When position provided, returns only tags in that position
-    def tags(position=nil)
-      return @tags unless position
-
-      unless @position_map
-        @position_map = {}
-        @tags.each do |t|
-          @position_map[t.position] = [] unless @position_map[t.position]
-          @position_map[t.position] << t
-        end
-      end
-
-      @position_map[position] || []
-    end
-
-    # Accesses tag by key or name
-    def [](name)
-      @map[name]
-    end
-
-    # Returns the formatter assigned to tags
-    def formatter
-      @formatter
-    end
-
-    # Sets the doc-formatter for all tags
-    def formatter=(doc_formatter)
-      @formatter = doc_formatter
-      @tags.each {|tag| tag.formatter = doc_formatter }
-    end
-
-    # Gives access to assets for all tags
-    def assets=(assets)
-      @tags.each {|tag| tag.assets = assets }
-    end
-
-    # Returns array of attributes to be shown in member signatures
-    # (and in order they should be shown in).
-    def signatures
-      if !@signatures
-        @signatures = @tags.find_all(&:signature).map do |tag|
-          s = tag.signature
-          s[:key] = tag.key
-          s
-        end
-      end
-      @signatures
-    end
-
-    private
-
-    def register_keys
-      @map = {}
-      @tags.each do |tag|
-        @map[tag.key] = tag
-        @map[tag.name] = tag
-      end
-    end
-  end
-
-end

data/lib/jsduck/meta_tag_renderer.rb

@@ -1,34 +0,0 @@
-require 'jsduck/meta_tag_registry'
-
-module JsDuck
-
-  # Performs the rendering of meta tags.
-  class MetaTagRenderer
-
-    # Renders full meta tags of a particular section.
-    #
-    # Returns array of rendered HTML or nil if no meta data.
-    def self.render(meta_data, position)
-      return if meta_data.size == 0
-
-      MetaTagRegistry.instance.tags(position).map do |tag|
-        meta_data[tag.key]
-      end
-    end
-
-    # Renders the meta-tag signatures for a class member.
-    # Returns a string.
-    def self.render_signature(member)
-      html = []
-      MetaTagRegistry.instance.signatures.each do |s|
-        if member[:meta][s[:key]]
-          title = s[:tooltip] ? "title='#{s[:tooltip]}'" : ""
-          html << "<strong class='#{s[:key]} signature' #{title}>#{s[:long]}</strong>"
-        end
-      end
-      html.join
-    end
-
-  end
-
-end

data/lib/jsduck/news.rb

@@ -1,128 +0,0 @@
-require 'jsduck/util/null_object'
-require 'jsduck/columns'
-
-module JsDuck
-
-  class News
-    # Creates News object from relations data when --import option
-    # specified.
-    def self.create(relations, doc_formatter, opts)
-      if opts[:imports].length > 0
-        News.new(relations, doc_formatter)
-      else
-        Util::NullObject.new(:to_html => "")
-      end
-    end
-
-    # Generates list of new classes & members in this version.
-    def initialize(relations, doc_formatter)
-      @doc_formatter = doc_formatter
-      @columns = Columns.new(:members)
-      @new_items = filter_new_items(relations)
-    end
-
-    # Returns the HTML
-    def to_html(style="")
-      return [
-        "<div id='news-content' style='#{style}'>",
-          "<div class='section'>",
-            "<h1>New in this version</h1>",
-            render_columns(@new_items),
-            "<div style='clear:both'></div>",
-          "</div>",
-        "</div>",
-      ].flatten.join("\n")
-    end
-
-    private
-
-    def filter_new_items(relations)
-      classes = []
-      new_items = []
-
-      relations.each do |cls|
-        if !cls[:meta][:private]
-          if cls[:meta][:new]
-            classes << cls
-          else
-            members = filter_new_members(cls)
-            if members.length > 0
-              new_items << {:name => cls[:name], :members => members}
-            end
-          end
-        end
-      end
-
-      new_items.sort! {|a, b| a[:name] <=> b[:name] }
-
-      # Place the new classes section at the beginning
-      if classes.length > 0
-        new_items.unshift({:name => "New classes", :members => classes})
-      end
-
-      new_items
-    end
-
-    def filter_new_members(cls)
-      members = []
-      cls.all_local_members.each do |m|
-        members << m if m[:meta][:new] && visible?(m)
-      end
-      members = discard_accessors(members)
-      members.sort! {|a, b| a[:name] <=> b[:name] }
-    end
-
-    def visible?(member)
-      !member[:meta][:private] && !member[:meta][:hide]
-    end
-
-    def discard_accessors(members)
-      accessors = {}
-      members.find_all {|m| m[:accessor] }.each do |cfg|
-        accessors["set" + upcase_first(cfg[:name])] = true
-        accessors["get" + upcase_first(cfg[:name])] = true
-        accessors[cfg[:name].downcase + "change"] = true if cfg[:evented]
-      end
-
-      members.reject {|m| accessors[m[:name]] }
-    end
-
-    def upcase_first(str)
-      str[0,1].upcase + str[1..-1]
-    end
-
-    def render_columns(new_items)
-      align = ["left-column", "middle-column", "right-column"]
-      i = -1
-      return @columns.split(new_items, 3).map do |col|
-        i += 1
-        [
-          "<div class='#{align[i]}'>",
-          render_col(col),
-          "</div>",
-        ]
-      end
-    end
-
-    def render_col(col)
-      return col.map do |item|
-        [
-          "<h3>#{item[:name]}</h3>",
-          "<ul class='links'>",
-          item[:members].map {|m| "<li>" + link(m) + "</li>" },
-          "</ul>",
-        ]
-      end
-    end
-
-    def link(m)
-      if m[:tagname] == :class
-        @doc_formatter.link(m[:name], nil, m[:name])
-      else
-        @doc_formatter.link(m[:owner], m[:name], m[:name], m[:tagname], m[:meta][:static])
-      end
-    end
-
-  end
-
-end

data/lib/jsduck/override.rb

@@ -1,87 +0,0 @@
-module JsDuck
-
-  class Override
-    def initialize(classes_hash)
-      @classes_hash = classes_hash
-    end
-
-    # Applies all override classes to target classes
-    # Returns all the processed override classes.
-    def process_all!
-      overrides = []
-
-      @classes_hash.each_value do |cls|
-        if cls[:override]
-          process(cls)
-          overrides << cls
-        end
-      end
-
-      overrides
-    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

data/lib/jsduck/renderer.rb

@@ -1,361 +0,0 @@
-require 'jsduck/util/html'
-require 'jsduck/meta_tag_renderer'
-require 'jsduck/signature_renderer'
-
-module JsDuck
-
-  # Ruby-side implementation of class docs Renderer.
-  # Uses PhantomJS to run Docs.Renderer JavaScript.
-  class Renderer
-    def initialize(opts)
-      @opts = opts
-    end
-
-    def render(cls)
-        @cls = cls
-        @signature = SignatureRenderer.new(cls)
-
-        return [
-          "<div>",
-            render_sidebar,
-            "<div class='doc-contents'>",
-              render_meta_data(@cls[:html_meta], :top),
-              render_private_class_notice,
-              @cls[:doc],
-              render_enum_class_notice,
-              render_meta_data(@cls[:html_meta], :bottom),
-            "</div>",
-            "<div class='members'>",
-              render_all_sections,
-            "</div>",
-          "</div>",
-        ].flatten.compact.join
-    end
-
-    def render_private_class_notice
-      return if !@cls[:private]
-      return [
-        "<p class='private'><strong>NOTE</strong> ",
-        "This is a private utility class for internal use by the framework. ",
-        "Don't rely on its existence.</p>",
-      ]
-    end
-
-    def render_enum_class_notice
-      return if !@cls[:enum]
-
-      if @cls[:enum][:doc_only]
-        first = @cls[:members][:property][0] || {:name => 'foo', :default => '"foo"'}
-        [
-          "<p class='enum'><strong>ENUM:</strong> ",
-          "This enumeration defines a set of String values. ",
-          "It exists primarily for documentation purposes - ",
-          "in code use the actual string values like #{first[:default]}, ",
-          "don't reference them through this class like #{@cls[:name]}.#{first[:name]}.</p>",
-        ]
-      else
-        [
-          "<p class='enum'><strong>ENUM:</strong> ",
-          "This enumeration defines a set of #{@cls[:enum][:type]} values.</p>",
-        ]
-      end
-    end
-
-    def render_meta_data(meta_data, position)
-      MetaTagRenderer.render(meta_data, position)
-    end
-
-    def render_sidebar
-      items = [
-        render_alternate_class_names,
-        render_tree,
-        render_dependencies(:mixins, "Mixins"),
-        render_dependencies(:parentMixins, "Inherited mixins"),
-        render_dependencies(:requires, "Requires"),
-        render_dependencies(:subclasses, "Subclasses"),
-        render_dependencies(:mixedInto, "Mixed into"),
-        render_dependencies(:uses, "Uses"),
-        @opts.source ? render_files : nil,
-      ]
-      if items.compact.length > 0
-        return ['<pre class="hierarchy">', items, '</pre>']
-      else
-        return nil
-      end
-    end
-
-    def render_alternate_class_names
-      return if @cls[:alternateClassNames].length == 0
-      return [
-        "<h4>Alternate names</h4>",
-        @cls[:alternateClassNames].map {|name| "<div class='alternate-class-name'>#{name}</div>" },
-      ]
-    end
-
-    def render_dependencies(type, title)
-      return if !@cls[type] || @cls[type].length == 0
-      return [
-        "<h4>#{title}</h4>",
-        @cls[type].map {|name| "<div class='dependency'>#{name.exists? ? render_link(name) : name}</div>" },
-      ]
-    end
-
-    def render_files
-      return if @cls[:files].length == 0 || @cls[:files][0][:filename] == ""
-      return [
-        "<h4>Files</h4>",
-        @cls[:files].map do |file|
-          url = "source/" + file[:href]
-          title = File.basename(file[:filename])
-          "<div class='dependency'><a href='#{url}' target='_blank'>#{title}</a></div>"
-        end
-      ]
-    end
-
-    # Take care of the special case where class has parent for which we have no docs.
-    # In that case the "extends" property exists but "superclasses" is empty.
-    # We still create the tree, but without links in it.
-    def render_tree
-      return if !@cls[:extends] || @cls[:extends] == "Object"
-
-      return [
-        "<h4>Hierarchy</h4>",
-        render_class_tree(@cls[:superclasses] + [@cls[:name]])
-      ]
-    end
-
-    def render_class_tree(classes, i=0)
-      return "" if classes.length <= i
-
-      name = classes[i]
-      return [
-        "<div class='subclass #{i == 0 ? 'first-child' : ''}'>",
-          classes.length-1 == i ? "<strong>#{name}</strong>" : (name.exists? ? render_link(name) : name),
-          render_class_tree(classes, i+1),
-        "</div>",
-      ]
-    end
-
-    def render_link(cls_name, member=nil)
-      id = member ? cls_name + "-" + member[:id] : cls_name
-      label = member ? cls_name + "." + member[:name] : cls_name
-      return "<a href='#!/api/#{id}' rel='#{id}' class='docClass'>#{label}</a>"
-    end
-
-    def render_all_sections
-      sections = [
-        {:type => :property, :title => "Properties"},
-        {:type => :method, :title => "Methods"},
-        {:type => :event, :title => "Events"},
-        {:type => :css_var, :title => "CSS Variables"},
-        {:type => :css_mixin, :title => "CSS Mixins"},
-      ]
-
-      render_configs_section + sections.map {|sec| render_section(sec) }
-    end
-
-    def render_configs_section
-      configs = @cls[:members][:cfg] + @cls[:statics][:cfg]
-
-      if configs.length > 0
-        required, optional = configs.partition {|c| c[:meta][:required] }
-        return [
-          "<div class='members-section'>",
-            required.length == 0 ? "<div class='definedBy'>Defined By</div>" : "",
-            "<h3 class='members-title icon-cfg'>Config options</h3>",
-            render_subsection(required, "Required Config options"),
-            render_subsection(optional, required.length > 0 ? "Optional Config options" : nil),
-          "</div>",
-        ]
-      else
-        return []
-      end
-    end
-
-    def render_section(sec)
-      members = @cls[:members][sec[:type]]
-      statics = @cls[:statics][sec[:type]]
-
-      # Skip rendering empty sections
-      if members.length > 0 || statics.length > 0
-        return [
-          "<div class='members-section'>",
-            statics.length == 0 ? "<div class='definedBy'>Defined By</div>" : "",
-            "<h3 class='members-title icon-#{sec[:type]}'>#{sec[:title]}</h3>",
-            render_subsection(members, statics.length > 0 ? "Instance #{sec[:title]}" : nil),
-            render_subsection(statics, "Static #{sec[:title]}"),
-          "</div>",
-        ]
-      else
-        return []
-      end
-    end
-
-    def render_subsection(members, title)
-      return if members.length == 0
-      index = 0
-      return [
-        "<div class='subsection'>",
-          title ? "<div class='definedBy'>Defined By</div><h4 class='members-subtitle'>#{title}</h3>" : "",
-          members.map {|m| index += 1; render_member(m, index == 1) },
-        "</div>",
-      ]
-    end
-
-    def render_member(m, is_first)
-      # use classname "first-child" when it's first member in its category
-      first_child = is_first ? "first-child" : ""
-      # shorthand to owner class
-      owner = m[:owner]
-      # is this method inherited from parent?
-      inherited = (owner != @cls[:name])
-
-      return [
-        "<div id='#{m[:id]}' class='member #{first_child} #{inherited ? 'inherited' : 'not-inherited'}'>",
-          # leftmost column: expand button
-          "<a href='#' class='side expandable'>",
-            "<span>&nbsp;</span>",
-          "</a>",
-          # member name and type + link to owner class and source
-          "<div class='title'>",
-            "<div class='meta'>",
-              inherited ? "<a href='#!/api/#{owner}' rel='#{owner}' class='defined-in docClass'>#{owner}</a>" :
-                          "<span class='defined-in' rel='#{owner}'>#{owner}</span>",
-              "<br/>",
-              @opts.source ? "<a href='source/#{m[:files][0][:href]}' target='_blank' class='view-source'>view source</a>" : "",
-            "</div>",
-            # method params signature or property type signature
-            render_signature(m),
-          "</div>",
-          # short and long descriptions
-          "<div class='description'>",
-            "<div class='short'>",
-              m[:shortDoc] ? m[:shortDoc] : m[:doc],
-            "</div>",
-            "<div class='long'>",
-              render_long_doc(m),
-            "</div>",
-          "</div>",
-        "</div>",
-      ]
-    end
-
-    def render_signature(m)
-      @signature.render(m)
-    end
-
-    def render_long_doc(m)
-      doc = []
-
-      doc << render_meta_data(m[:html_meta], :top)
-
-      doc << m[:doc]
-
-      if m[:default] && m[:default] != "undefined"
-        doc << "<p>Defaults to: <code>" + Util::HTML.escape(m[:default]) + "</code></p>"
-      end
-
-      doc << render_meta_data(m[:html_meta], :bottom)
-
-      doc << render_params_and_return(m)
-
-      if m[:overrides]
-        overrides = m[:overrides].map {|o| render_link(o[:owner], o) }.join(", ")
-        doc << "<p>Overrides: #{overrides}</p>"
-      end
-
-      doc
-    end
-
-    # Handles both rendering of method parameters and return value.
-    # Plus the rendering of object properties, which could also be
-    # functions in which case they too will be rendered with
-    # parameters and return value.
-    def render_params_and_return(item)
-      doc = []
-
-      if item[:params] && item[:params].length > 0
-        params = item[:params]
-      elsif item[:properties] && item[:properties].length > 0
-        params = item[:properties]
-        # If the name of last property is "return"
-        # remove it from params list and handle it separately afterwards
-        if params.last[:name] == "return"
-          ret = params.last
-          params = params.slice(0, params.length-1)
-        end
-      end
-
-      if params
-        if item[:type] == "Function" || item[:tagname] == :method || item[:tagname] == :event
-          doc << '<h3 class="pa">Parameters</h3>'
-        end
-        doc << [
-          "<ul>",
-          params.map {|p| render_long_param(p) },
-          "</ul>",
-        ]
-      end
-
-      if item[:return]
-        doc << render_return(item[:return])
-      elsif ret
-        doc << render_return(ret)
-      end
-
-      if item[:throws]
-        doc << render_throws(item[:throws])
-      end
-
-      doc
-    end
-
-    def render_long_param(p)
-      return [
-        "<li>",
-          "<span class='pre'>#{p[:name]}</span> : ",
-          p[:html_type],
-          p[:optional] ? " (optional)" : "",
-          "<div class='sub-desc'>",
-            p[:doc],
-            p[:default] ? "<p>Defaults to: <code>#{Util::HTML.escape(p[:default])}</code></p>" : "",
-            p[:properties] && p[:properties].length > 0 ? render_params_and_return(p) : "",
-          "</div>",
-        "</li>",
-      ]
-    end
-
-    def render_return(ret)
-      return if ret[:type] == "undefined"
-      return [
-        "<h3 class='pa'>Returns</h3>",
-        "<ul>",
-          "<li>",
-            "<span class='pre'>#{ret[:html_type]}</span>",
-            "<div class='sub-desc'>",
-              ret[:doc],
-              ret[:properties] && ret[:properties].length > 0 ? render_params_and_return(ret) : "",
-            "</div>",
-          "</li>",
-        "</ul>",
-      ]
-    end
-
-    def render_throws(throws)
-      return [
-        "<h3 class='pa'>Throws</h3>",
-        "<ul>",
-          throws.map do |thr|
-            [
-              "<li>",
-                "<span class='pre'>#{thr[:html_type]}</span>",
-                "<div class='sub-desc'>#{thr[:doc]}</div>",
-              "</li>",
-            ]
-          end,
-        "</ul>",
-      ]
-    end
-  end
-
-end