solvas-jsduck 6.0.0.beta.1888

data/lib/jsduck/render/sidebar.rb

@@ -0,0 +1,97 @@
+module JsDuck
+  module Render
+
+    # Generates HTML for the class hierarchy sidebar inside class
+    # documentation.
+    class Sidebar
+      def initialize(opts)
+        @opts = opts
+      end
+
+      # Renders a sidebar for given class.
+      # Returns Array of HTML or nil.
+      def render(cls)
+        items = [
+          render_alternate_class_names(cls[:alternateClassNames]),
+          render_tree(cls),
+          render_dependencies(cls[:mixins], "Mixins"),
+          render_dependencies(cls[:parentMixins], "Inherited mixins"),
+          render_dependencies(cls[:requires], "Requires"),
+          render_dependencies(cls[:subclasses], "Subclasses"),
+          render_dependencies(cls[:mixedInto], "Mixed into"),
+          render_dependencies(cls[:uses], "Uses"),
+          render_files(cls[:files])
+        ]
+
+        if items.compact.length > 0
+          return ['<pre class="hierarchy">', items, '</pre>']
+        else
+          return nil
+        end
+      end
+
+      private
+
+      def render_alternate_class_names(names)
+        return if names.length == 0
+
+        return [
+          "<h4>Alternate names</h4>",
+          names.map {|name| "<div class='alternate-class-name'>#{name}</div>" },
+        ]
+      end
+
+      def render_dependencies(names, title)
+        return if !names || names.length == 0
+
+        return [
+          "<h4>#{title}</h4>",
+          names.map {|name| "<div class='dependency'>#{name.exists? ? render_link(name) : name}</div>" },
+        ]
+      end
+
+      def render_files(files)
+        return if !@opts.source || files.length == 0 || files[0][:filename] == ""
+
+        return [
+          "<h4>Files</h4>",
+          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(cls)
+        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)
+        "<a href='#!/api/#{cls_name}' rel='#{cls_name}' class='docClass'>#{cls_name}</a>"
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/render/signature_util.rb

@@ -0,0 +1,14 @@
+module JsDuck
+  module Render
+
+    # Helper method for rendering the link in method/property signature
+    class SignatureUtil
+
+      def self.link(class_name, member_id, text)
+        "<a href='#!/api/#{class_name}-#{member_id}' class='name expandable'>#{text}</a>"
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/render/subproperties.rb

@@ -0,0 +1,117 @@
+require 'jsduck/util/html'
+require 'jsduck/util/singleton'
+require 'jsduck/tag_registry'
+
+module JsDuck
+  module Render
+
+    # Renders params, return values and everything else that can have
+    # nested subproperties.
+    class Subproperties
+      include Util::Singleton
+
+      # Renders object properties, which could also be functions in
+      # which case they will be rendered with parameters and return
+      # value.
+      def render(item)
+        doc = []
+
+        if item[:type] == "Function"
+          params = item[:properties]
+          # If the name of last property is "return" remove it from
+          # properties list and format as a return value afterwards.
+          if item[:properties].last[:name] == "return"
+            ret = params.last
+            params = params.slice(0, params.length-1)
+          end
+
+          doc << render_params(params)
+          doc << render_return(ret) if ret
+        else
+          doc << render_list(item[:properties])
+        end
+
+        doc
+      end
+
+      def render_params(params)
+        return [
+          '<h3 class="pa">Parameters</h3>',
+          render_list(params),
+        ]
+      end
+
+      def render_list(params)
+        return [
+          "<ul>",
+          params.map {|p| render_single_param(p) },
+          "</ul>",
+        ]
+      end
+
+      def render_single_param(p)
+        return [
+          "<li>",
+            "<span class='pre'>#{p[:name]}</span> : ",
+            p[:html_type],
+            p[:optional] ? " (optional)" : "",
+            p[:new] ? render_new : "",
+            "<div class='sub-desc'>",
+              p[:doc],
+              p[:default] ? "<p>Defaults to: <code>#{Util::HTML.escape(p[:default])}</code></p>" : "",
+              p[:since] ? render_since(p) : "",
+              p[:properties] && p[:properties].length > 0 ? render(p) : "",
+            "</div>",
+          "</li>",
+        ]
+      end
+
+      def render_new
+        signature = TagRegistry.get_by_name(:new).signature
+        return [
+          "<span class='signature'>",
+            "<span class='new' title='#{signature[:tooltip]}'>",
+              signature[:long],
+            "</span>",
+          "</span>",
+        ]
+      end
+
+      def render_since(param)
+        TagRegistry.get_by_name(:since).to_html(param)
+      end
+
+      def render_return(ret)
+        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(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
+end

data/lib/jsduck/render/tags.rb

@@ -0,0 +1,50 @@
+require 'jsduck/tag_registry'
+
+module JsDuck
+  module Render
+
+    # Performs the rendering of tags.
+    class Tags
+      # Renders tags of a particular section.
+      #
+      # Takes member or class hash.
+      # Returns array of rendered HTML.
+      def self.render(member)
+        renderers.map do |tag|
+          if member[tag.tagname]
+            tag.to_html(member)
+          else
+            nil
+          end
+        end
+      end
+
+      # Returns tags for rendering HTML, sorted in the order they should
+      # appear in final output. Sorting order is determined by the
+      # numeric :html_position field.
+      def self.renderers
+        if !@renderers
+          @renderers = TagRegistry.tags.find_all(&:html_position)
+          @renderers.sort! {|a, b| a.html_position <=> b.html_position }
+        end
+
+        @renderers
+      end
+
+      # Renders the signatures for a class member.
+      # Returns a string.
+      def self.render_signature(member)
+        html = []
+        TagRegistry.signatures.each do |s|
+          if member[s[:tagname]]
+            title = s[:tooltip] ? "title='#{s[:tooltip]}'" : ""
+            html << "<span class='#{s[:tagname]}' #{title}>#{s[:long]}</span>"
+          end
+        end
+        '<span class="signature">' + html.join + "</span>"
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/source/file.rb

@@ -0,0 +1,89 @@
+require 'jsduck/util/html'
+
+module JsDuck
+  module Source
+
+    # Represents one JavaScript or SCSS source file.
+    #
+    # The filename parameter determines whether it's parsed as
+    # JavaScript (the default) or SCSS.
+    class File
+      attr_reader :filename
+      attr_reader :contents
+      attr_reader :docs
+      attr_reader :html_filename
+
+      def initialize(contents, docs, filename="")
+        @contents = contents
+        @docs = docs
+        @filename = filename
+        @html_filename = ""
+        @links = {}
+
+        @docs.map do |docset|
+          link(docset)
+        end
+      end
+
+      # loops through each doc-object in file
+      def each(&block)
+        @docs.each(&block)
+      end
+
+      # Sets the html filename of this file,
+      # updating also all doc-objects linking this file
+      def html_filename=(html_filename)
+        @html_filename = html_filename
+        @links.each_value do |line|
+          line.each do |link|
+            link[:file][:html_filename] = @html_filename
+            link[:file][:href] = @html_filename + "#" + id(link[:doc])
+          end
+        end
+      end
+
+      # Returns source code as HTML with lines starting doc-comments specially marked.
+      def to_html
+        linenr = 0
+        lines = []
+        # Use #each_line instead of #lines to support Ruby 1.6
+        @contents.each_line do |line|
+          linenr += 1;
+          line = Util::HTML.escape(line)
+          # wrap the line in as many spans as there are links to this line number.
+          if @links[linenr]
+            @links[linenr].each do |link|
+              line = "<span id='#{id(link[:doc])}'>#{line}</span>"
+            end
+          end
+          lines << line
+        end
+        lines.join()
+      end
+
+      def id(doc)
+        if doc[:tagname] == :class
+          doc[:name].gsub(/\./, '-')
+        else
+          # when creation of global class is skipped,
+          # this owner property can be nil.
+          (doc[:owner] || "global").gsub(/\./, '-') + "-" + doc[:id]
+        end
+      end
+
+      private
+
+      # Creates two-way link between sourcefile and doc-object.
+      # Returns the modified doc-object after done.
+      def link(docset)
+        file = docset[:files].first
+        linenr = file[:linenr]
+        @links[linenr] = [] unless @links[linenr]
+        @links[linenr] << {:doc => docset, :file => file}
+        docset
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/tag/abstract.rb

@@ -0,0 +1,11 @@
+require "jsduck/tag/boolean_tag"
+
+module JsDuck::Tag
+  class Abstract < BooleanTag
+    def initialize
+      @pattern = "abstract"
+      @signature = {:long => "abstract", :short => "ABS"}
+      super
+    end
+  end
+end

data/lib/jsduck/tag/accessor.rb

@@ -0,0 +1,10 @@
+require "jsduck/tag/boolean_tag"
+
+module JsDuck::Tag
+  class Accessor < BooleanTag
+    def initialize
+      @pattern = "accessor"
+      super
+    end
+  end
+end

data/lib/jsduck/tag/alias.rb

@@ -0,0 +1,42 @@
+require "jsduck/tag/inheritdoc"
+require "jsduck/js/utils"
+
+module JsDuck::Tag
+  class Alias < Inheritdoc
+    def initialize
+      @pattern = "alias"
+      @tagname = :aliases
+      @repeatable = true
+      @ext_define_pattern = "alias"
+      @ext_define_default = {:aliases => []}
+    end
+
+    # For backwards compatibility decide whether the @alias was used
+    # as @inheritdoc (@alias used to have the meaning of @inheritdoc
+    # before) or as a real Ext4 style alias definition.
+    def parse_doc(p, pos)
+      if p.look(/([\w.]+)?#\w+/)
+        parse_as_inheritdoc(p)
+      else
+        parse_as_alias(p)
+      end
+    end
+
+    # @alias widget.foo
+    def parse_as_alias(p)
+      {
+        :tagname => :aliases,
+        :name => p.ident_chain,
+      }
+    end
+
+    def process_doc(h, tags, pos)
+      h[:aliases] = tags.map {|tag| tag[:name] }
+    end
+
+    def parse_ext_define(cls, ast)
+      cls[:aliases] += JsDuck::Js::Utils.make_string_list(ast)
+    end
+
+  end
+end

data/lib/jsduck/tag/alternate_class_names.rb

@@ -0,0 +1,13 @@
+require "jsduck/tag/class_list_tag"
+
+module JsDuck::Tag
+  class AlternateClassNames < ClassListTag
+    def initialize
+      @pattern = ["alternateClassName", "alternateClassNames"]
+      @tagname = :alternateClassNames
+      @repeatable = true
+      @ext_define_pattern = "alternateClassName"
+      @ext_define_default = {:alternateClassNames => []}
+    end
+  end
+end