jsduck 4.10.4 → 5.0.0.beta01

data/lib/jsduck/process/return_values.rb

@@ -0,0 +1,72 @@
+module JsDuck
+  module Process
+
+    # Auto-detector return values and @chainable tags.
+    #
+    # Adds @chainable tag when doc-comment contains @return {OwnerClass}
+    # this.  Also the other way around: when @chainable found, adds
+    # appropriate @return.
+    class ReturnValues
+      def initialize(relations)
+        @relations = relations
+        @cls = nil
+      end
+
+      def process_all!
+        @relations.each do |cls|
+          @cls = cls
+          cls.find_members(:tagname => :method, :local => true, :static => false).each do |m|
+            process(m)
+          end
+        end
+      end
+
+      private
+
+      def process(m)
+        if constructor?(m)
+          add_return_new(m)
+        elsif chainable?(m)
+          add_return_this(m)
+        elsif returns_this?(m)
+          add_chainable(m)
+        end
+      end
+
+      def constructor?(m)
+        m[:name] == "constructor"
+      end
+
+      def chainable?(m)
+        m[:chainable]
+      end
+
+      def returns_this?(m)
+        m[:return] && m[:return][:type] == @cls[:name] && m[:return][:doc] =~ /\Athis\b/
+      end
+
+      def add_chainable(m)
+        m[:chainable] = true
+      end
+
+      def add_return_this(m)
+        if m[:return] == nil
+          m[:return] = {:type => @cls[:name], :doc => "this"}
+        end
+      end
+
+      def add_return_new(m)
+        if m[:return] == nil || m[:return][:type] == "Object"
+          # Create a whole new :return hash.
+          # If we were to just change the :type field it would modify
+          # the type of all the inherited constructor docs.
+          m[:return] = {
+            :type => @cls[:name],
+            :doc => m[:return] ? m[:return][:doc] : "",
+          }
+        end
+      end
+    end
+
+  end
+end

data/lib/jsduck/process/versions.rb

@@ -0,0 +1,102 @@
+require 'jsduck/process/importer'
+require 'jsduck/tag_registry'
+
+module JsDuck
+  module Process
+
+    # Generates @since and @new tags by importing JSDuck exports of
+    # older versions of the same project and looking in which version
+    # a class or method first appeared.
+    #
+    # Additionally here the tooltip text for @new tag gets injected.
+    class Versions
+      def initialize(relations, opts={}, importer=nil)
+        @relations = relations
+        @opts = opts
+        # Allow different importer to be injected for testing
+        @importer = importer || Process::Importer.new
+      end
+
+      # Loads in exported docs and generates @since and @new tags.
+      def process_all!
+        init_new_tag_tooltip!
+
+        if @opts[:imports].length > 0
+          generate_since_tags(@importer.import(@opts[:imports]))
+        end
+      end
+
+      private
+
+      # Initializes the tooltip text for the signature of @new tag.
+      def init_new_tag_tooltip!
+        signature = TagRegistry.get_by_name(:new).signature
+        if @opts[:new_since]
+          signature[:tooltip] = "New since #{@opts[:new_since]}"
+        elsif @opts[:imports].length > 0
+          signature[:tooltip] = "New since #{@opts[:imports].last[:version]}"
+        end
+      end
+
+      # Using the imported versions data, adds @since tags to all
+      # classes/members.
+      def generate_since_tags(versions)
+        new_versions = build_new_versions_map(versions)
+
+        @relations.each do |cls|
+          v = cls[:since] || class_since(versions, cls)
+          cls[:since] = v
+          cls[:new] = true if new_versions[v]
+
+          cls.all_local_members.each do |m|
+            v = m[:since] || member_since(versions, cls, m)
+            m[:since] = v
+            m[:new] = true if new_versions[v]
+          end
+        end
+      end
+
+      # Generates a lookup table of versions that we are going to label
+      # with @new tags.  By default we use the latest version, otherwise
+      # use all versions since the latest.
+      def build_new_versions_map(versions)
+        new_versions = {}
+
+        if @opts[:new_since]
+          versions.map {|v| v[:version] }.each do |v|
+            if v == @opts[:new_since] || !new_versions.empty?
+              new_versions[v] = true
+            end
+          end
+        else
+          new_versions[versions.last[:version]] = true
+        end
+
+        new_versions
+      end
+
+      def member_since(versions, cls, m)
+        versions.each do |ver|
+          c = ver[:classes][cls[:name]]
+          return ver[:version] if c && c[m[:id]]
+          cls[:alternateClassNames].each do |name|
+            c = ver[:classes][name]
+            return ver[:version] if c && c[m[:id]]
+          end
+        end
+      end
+
+      # Returns name of the version since which the class is available
+      def class_since(versions, cls)
+        versions.each do |ver|
+          return ver[:version] if ver[:classes][cls[:name]]
+          cls[:alternateClassNames].each do |name|
+            return ver[:version] if ver[:classes][name]
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/relations.rb

@@ -50,6 +50,11 @@ module JsDuck
       @classes.each(&block)
     end
 
+    # Used in tests to check the nr of classes.
+    def length
+      @classes.length
+    end
+
     # Returns list of all classes.  This method allows us to treat
     # Relations as array and therefore easily mock it
     def to_a

data/lib/jsduck/render/class.rb

@@ -0,0 +1,144 @@
+require 'jsduck/render/signature'
+require 'jsduck/render/tags'
+require 'jsduck/render/sidebar'
+
+module JsDuck
+  module Render
+
+    # Renders the whole documentation page for a class.
+    class Class
+      def initialize(opts)
+        @opts = opts
+      end
+
+      def render(cls)
+        @cls = cls
+        @signature = Render::Signature.new(cls)
+
+        return [
+          "<div>",
+            render_sidebar,
+            "<div class='doc-contents'>",
+              render_tags(@cls),
+            "</div>",
+            "<div class='members'>",
+              render_all_sections,
+            "</div>",
+          "</div>",
+        ].flatten.compact.join
+      end
+
+      private
+
+      def render_tags(member)
+        Render::Tags.render(member)
+      end
+
+      def render_sidebar
+        Render::Sidebar.new(@opts).render(@cls)
+      end
+
+      def render_all_sections
+        TagRegistry.member_types.map do |member_type|
+          render_section(member_type)
+        end
+      end
+
+      def render_section(sec)
+        members = @cls[:members][sec[:name]] + @cls[:statics][sec[:name]]
+
+        # Skip rendering empty sections
+        return [] if members.length == 0
+
+        # Split members array into subsections
+        subsections = Array(sec[:subsections]).map do |subsec|
+          ms = members.find_all {|m| test_filter(m, subsec[:filter]) }
+          if ms.length > 0
+            {:title => subsec[:title], :members => ms, :default => subsec[:default]}
+          else
+            nil
+          end
+        end.compact
+
+        # Print no subsections when no subsections defined or there's
+        # just single subsection which is the default one.
+        if subsections.length == 0 || subsections.length == 1 && subsections[0][:default]
+          return [
+            "<div class='members-section'>",
+              "<div class='definedBy'>Defined By</div>",
+              "<h3 class='members-title icon-#{sec[:name]}'>#{sec[:title]}</h3>",
+              render_subsection(members, nil),
+            "</div>",
+          ]
+        end
+
+        return [
+          "<div class='members-section'>",
+          "<h3 class='members-title icon-#{sec[:name]}'>#{sec[:title]}</h3>",
+          subsections.map {|ss| render_subsection(ss[:members], ss[:title]) },
+          "</div>",
+        ]
+      end
+
+      # Returns true if member matches the conditions described by a
+      # subsection filter.
+      def test_filter(member, filter)
+        filter.each_pair do |field, truthy|
+          return false unless truthy ? member[field] : !member[field]
+        end
+        return true
+      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
+              @signature.render(m),
+            "</div>",
+            # short and long descriptions
+            "<div class='description'>",
+              "<div class='short'>",
+                m[:short_doc] ? m[:short_doc] : m[:doc],
+              "</div>",
+              "<div class='long'>",
+                render_tags(m),
+              "</div>",
+            "</div>",
+          "</div>",
+        ]
+      end
+
+    end
+
+  end
+end

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.rb

@@ -0,0 +1,94 @@
+require 'jsduck/render/tags'
+require 'jsduck/tag_registry'
+
+module JsDuck
+  module Render
+
+    # Performs the rendering of member signatures.
+    class Signature
+      # Initializes the renderer for rendering members of the given
+      # class.
+      def initialize(cls)
+        @cls = cls
+      end
+
+      # Renders signature of the given member.
+      def render(member)
+        # Keep the code simpler by not passing around the member hash
+        @m = member
+
+        return [
+          render_new,
+          render_link,
+          render_type,
+          render_tag_signature,
+        ]
+      end
+
+      private
+
+      def render_new
+        constructor? ? "<strong class='new-keyword'>new</strong>" : ""
+      end
+
+      def render_link
+        "<a href='#{render_url}' class='name #{render_expandable}'>#{render_name}</a>"
+      end
+
+      def render_url
+        "#!/api/#{@m[:owner]}-#{@m[:id]}"
+      end
+
+      def render_expandable
+        @m[:short_doc] ? "expandable" : "not-expandable"
+      end
+
+      def render_name
+        constructor? ? @cls[:name] : @m[:name]
+      end
+
+      def constructor?
+        @m[:tagname] == :method && @m[:name] == "constructor"
+      end
+
+      def render_type
+        if like_property?
+          render_property_type
+        else
+          render_params + render_return
+        end
+      end
+
+      def like_property?
+        TagRegistry.member_type_names(:property_like).include?(@m[:tagname])
+      end
+
+      def render_property_type
+        "<span> : #{@m[:html_type]}</span>"
+      end
+
+      def render_params
+        ps = @m[:params].map {|p| render_single_param(p) }.join(", ")
+        "( <span class='pre'>#{ps}</span> )"
+      end
+
+      def render_single_param(param)
+        param[:optional] ? "["+param[:name]+"]" : param[:name]
+      end
+
+      def render_return
+        method_with_return? ? (" : " + @m[:return][:html_type]) : ""
+      end
+
+      def method_with_return?
+        @m[:tagname] == :method && @m[:return] != nil
+      end
+
+      def render_tag_signature
+        Render::Tags.render_signature(@m)
+      end
+
+    end
+
+  end
+end