solvas-jsduck 6.0.0.beta.1888

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,137 @@
+require 'jsduck/process/importer'
+require 'ostruct'
+
+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.
+    class Versions
+      def initialize(relations, opts=OpenStruct.new, importer=Process::Importer.new)
+        @relations = relations
+        @opts = opts
+        @importer = importer
+      end
+
+      # Loads in exported docs and generates @since and @new tags.
+      def process_all!
+        if @opts.import.length > 0
+          @versions = @importer.import(@opts.import)
+          add_since_tags
+        end
+      end
+
+      private
+
+      # classes...
+
+      # Using the imported versions data, adds @since tags to all
+      # classes/members/params.
+      def add_since_tags
+        @relations.each do |cls|
+          v = cls[:since] || class_since(cls)
+          cls[:since] = v
+          cls[:new] = true if is_new?(v)
+
+          add_members_since_tags(cls)
+        end
+      end
+
+      # Returns name of the version since which the class is available
+      def class_since(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
+
+      # members...
+
+      def add_members_since_tags(cls)
+        cls.all_local_members.each do |m|
+          # Remember the initial explicit @since tag value
+          # to disable params processing when it's present.
+          explicit_since = m[:since]
+
+          v = m[:since] || member_since(cls, m)
+          m[:since] = v
+          m[:new] = true if is_new?(v)
+
+          add_params_since_tags(cls, m, v) unless explicit_since
+        end
+      end
+
+      def member_since(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
+
+      # params...
+
+      def add_params_since_tags(cls, member, member_version)
+        Array(member[:params]).each_with_index do |p, i|
+          v = param_since(cls, member, i)
+          if v != member_version
+            p[:since] = v
+            p[:new] = true if is_new?(v)
+          end
+        end
+      end
+
+      def param_since(cls, m, i)
+        @versions.each do |ver|
+          c = ver[:classes][cls[:name]]
+          return ver[:version] if c && has_param?(c[m[:id]], i)
+          cls[:alternateClassNames].each do |name|
+            c = ver[:classes][name]
+            return ver[:version] if c && has_param?(c[m[:id]], i)
+          end
+        end
+      end
+
+      # Because parameters can be renamed between versions, only
+      # consider parameter count.
+      def has_param?(member, param_index)
+        member && member.respond_to?(:length) && member.length > param_index
+      end
+
+      # helpers...
+
+      # Should items introduced in given version be marked as new?
+      def is_new?(version_nr)
+        @new_versions = new_versions_map unless @new_versions
+        @new_versions[version_nr]
+      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 new_versions_map
+        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
+
+    end
+
+  end
+end

data/lib/jsduck/relations.rb

@@ -0,0 +1,95 @@
+require 'jsduck/external_classes'
+
+module JsDuck
+
+  # Provides information about relations between classes.
+  #
+  # Also provides a place to look up classes by name.
+  #
+  # The constructor is initialized with array of all available classes
+  # and list of class names to ignore.  By default the latter list
+  # contains only JavaScript base class "Object".
+  class Relations
+    # Returns list of all classes
+    attr_reader :classes
+
+    def initialize(classes = [], ignorables = [])
+      @classes = classes
+      @external_classes = ExternalClasses.new(ignorables)
+
+      # First build class lookup table; building lookup tables for
+      # mixins and subclasses will depend on that.
+      @lookup = {}
+      @classes.each do |cls|
+        @lookup[cls[:name]] = cls
+        (cls[:alternateClassNames] || []).each do |alt_name|
+          @lookup[alt_name] = cls
+        end
+        cls.relations = self
+      end
+
+      @subs = {}
+      @mixes = {}
+      @classes.each do |cls|
+        reg_subclasses(cls)
+        reg_mixed_into(cls)
+      end
+    end
+
+    # Looks up class by name, nil if not found
+    def [](classname)
+      @lookup[classname]
+    end
+
+    # Returns true if class is in list of ignored classes.
+    def ignore?(classname)
+      @external_classes.is?(classname)
+    end
+
+    def each(&block)
+      @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
+      @classes
+    end
+
+    def reg_subclasses(cls)
+      if !cls.parent
+        # do nothing
+      elsif @subs[cls.parent[:name]]
+        @subs[cls.parent[:name]] << cls
+      else
+        @subs[cls.parent[:name]] = [cls]
+      end
+    end
+
+    # Returns subclasses of particular class, empty array if none
+    def subclasses(cls)
+      @subs[cls[:name]] || []
+    end
+
+    def reg_mixed_into(cls)
+      cls.mixins.each do |mix|
+        if @mixes[mix[:name]]
+          @mixes[mix[:name]] << cls
+        else
+          @mixes[mix[:name]] = [cls]
+        end
+      end
+    end
+
+    # Returns classes having particular mixin, empty array if none
+    def mixed_into(cls)
+      @mixes[cls[:name]] || []
+    end
+  end
+
+end

data/lib/jsduck/render/class.rb

@@ -0,0 +1,152 @@
+require 'jsduck/render/tags'
+require 'jsduck/render/sidebar'
+require 'jsduck/tag_registry'
+require 'jsduck/member_registry'
+
+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
+
+        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
+        MemberRegistry.definitions.map do |member_def|
+          render_section(member_def)
+        end
+      end
+
+      def render_section(sec)
+        members = @cls[:members].find_all {|m| m[:tagname] == 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>",
+              render_member_signature(m),
+              render_tag_signature(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
+
+      def render_member_signature(m)
+        TagRegistry.get_by_name(m[:tagname]).to_html(m, @cls)
+      end
+
+      def render_tag_signature(m)
+        Render::Tags.render_signature(m)
+      end
+
+    end
+
+  end
+end