jsduck 4.0.1 → 4.1.1

data/lib/jsduck/override.rb

@@ -27,7 +27,7 @@ module JsDuck
       target = @classes_hash[override[:override]]
       unless target
         ctx = override[:files][0]
-        return Logger.instance.warn(:extend, "Class #{override[:override]} not found", ctx[:filename], ctx[:linenr])
+        return Logger.warn(:extend, "Class #{override[:override]} not found", ctx[:filename], ctx[:linenr])
       end
 
       # Combine comments of classes
@@ -64,15 +64,11 @@ module JsDuck
     # helpers
 
     def each_member(cls)
-      [:members, :statics].each do |category|
-        cls[category].each_pair do |key, members|
-          members.each {|m| yield m }
-        end
-      end
+      cls[:members].each {|m| yield m }
     end
 
     def add_member(cls, m)
-      cls[m[:static] ? :statics : :members][m[:tagname]] << m
+      cls[:members] << m
     end
 
     def add_doc(m, doc)

data/lib/jsduck/relations.rb

@@ -20,7 +20,7 @@ module JsDuck
       # mixins and subclasses will depend on that.
       @lookup = {}
       @classes.each do |cls|
-        @lookup[cls.full_name] = cls
+        @lookup[cls[:name]] = cls
         (cls[:alternateClassNames] || []).each do |alt_name|
           @lookup[alt_name] = cls
         end
@@ -58,31 +58,31 @@ module JsDuck
     def reg_subclasses(cls)
       if !cls.parent
         # do nothing
-      elsif @subs[cls.parent.full_name]
-        @subs[cls.parent.full_name] << cls
+      elsif @subs[cls.parent[:name]]
+        @subs[cls.parent[:name]] << cls
       else
-        @subs[cls.parent.full_name] = [cls]
+        @subs[cls.parent[:name]] = [cls]
       end
     end
 
     # Returns subclasses of particular class, empty array if none
     def subclasses(cls)
-      @subs[cls.full_name] || []
+      @subs[cls[:name]] || []
     end
 
     def reg_mixed_into(cls)
       cls.mixins.each do |mix|
-        if @mixes[mix.full_name]
-          @mixes[mix.full_name] << cls
+        if @mixes[mix[:name]]
+          @mixes[mix[:name]] << cls
         else
-          @mixes[mix.full_name] = [cls]
+          @mixes[mix[:name]] = [cls]
         end
       end
     end
 
     # Returns classes having particular mixin, empty array if none
     def mixed_into(cls)
-      @mixes[cls.full_name] || []
+      @mixes[cls[:name]] || []
     end
   end
 

data/lib/jsduck/renderer.rb

@@ -1,4 +1,4 @@
-require 'jsduck/html'
+require 'jsduck/util/html'
 require 'jsduck/meta_tag_renderer'
 require 'jsduck/signature_renderer'
 
@@ -252,7 +252,7 @@ module JsDuck
       doc << m[:doc]
 
       if m[:default] && m[:default] != "undefined"
-        doc << "<p>Defaults to: <code>" + HTML.escape(m[:default]) + "</code></p>"
+        doc << "<p>Defaults to: <code>" + Util::HTML.escape(m[:default]) + "</code></p>"
       end
 
       doc << render_meta_data(m[:html_meta], :bottom)
@@ -318,7 +318,7 @@ module JsDuck
           p[:optional] ? " (optional)" : "",
           "<div class='sub-desc'>",
             p[:doc],
-            p[:default] ? "<p>Defaults to: <code>#{HTML.escape(p[:default])}</code></p>" : "",
+            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>",

data/lib/jsduck/return_values.rb

@@ -0,0 +1,72 @@
+module JsDuck
+
+  # 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
+    # Only this static method of this class should be called.
+    def self.auto_detect(relations)
+      ReturnValues.new(relations).process_all!
+    end
+
+    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[:meta][:chainable]
+    end
+
+    def returns_this?(m)
+      m[:return] && m[:return][:type] == @cls[:name] && m[:return][:doc] =~ /\Athis\b/
+    end
+
+    def add_chainable(m)
+      m[:meta][:chainable] = true
+    end
+
+    def add_return_this(m)
+      if m[:return][:type] == "undefined" && m[:return][:doc] == ""
+        m[:return] = {:type => @cls[:name], :doc => "this"}
+      end
+    end
+
+    def add_return_new(m)
+      if m[:return][:type] == "undefined"
+        # 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][:doc]}
+      end
+    end
+  end
+
+end

data/lib/jsduck/search_data.rb

@@ -1,3 +1,5 @@
+require 'jsduck/icons'
+require 'jsduck/class_name'
 
 module JsDuck
 
@@ -22,15 +24,9 @@ module JsDuck
           end
         end
 
-        [:members, :statics].each do |group|
-          cls[group].each_key do |type|
-            cls.members(type, group).each do |m|
-              # skip inherited items and constructors
-              if m[:owner] == cls.full_name && m[:name] != cls.short_name
-                list << member_node(m, cls)
-              end
-            end
-          end
+        # add all local members, but skip constructors
+        cls[:members].each do |m|
+          list << member_node(m, cls) unless m[:name] == ClassName.short(cls[:name])
         end
       end
 
@@ -49,8 +45,8 @@ module JsDuck
       return {
         :name => name,
         :fullName => alias_display_name(key)+": "+name,
-        :icon => cls.icon + "-redirect",
-        :url => "#!/api/" + cls.full_name,
+        :icon => Icons::class_icon(cls) + "-redirect",
+        :url => "#!/api/" + cls[:name],
         :meta => cls[:meta],
         :sort => 0,
       }
@@ -58,10 +54,10 @@ module JsDuck
 
     def class_node(cls)
       return {
-        :name => cls.short_name,
-        :fullName => cls.full_name,
-        :icon => cls.icon,
-        :url => "#!/api/" + cls.full_name,
+        :name => ClassName.short(cls[:name]),
+        :fullName => cls[:name],
+        :icon => Icons::class_icon(cls),
+        :url => "#!/api/" + cls[:name],
         :meta => cls[:meta],
         :sort => 1,
       }
@@ -69,11 +65,11 @@ module JsDuck
 
     def alt_node(name, cls)
       return {
-        :name => Class.short_name(name),
+        :name => ClassName.short(name),
         :fullName => name,
         :type => :class,
-        :icon => cls.icon + "-redirect",
-        :url => "#!/api/" + cls.full_name,
+        :icon => Icons::class_icon(cls) + "-redirect",
+        :url => "#!/api/" + cls[:name],
         :meta => cls[:meta],
         :sort => 2,
       }
@@ -82,9 +78,9 @@ module JsDuck
     def member_node(member, cls)
       return {
         :name => member[:name],
-        :fullName => cls.full_name + "." + member[:name],
+        :fullName => cls[:name] + "." + member[:name],
         :icon => "icon-" + member[:tagname].to_s,
-        :url => "#!/api/" + cls.full_name + "-" + member[:id],
+        :url => "#!/api/" + cls[:name] + "-" + member[:id],
         :meta => member[:meta],
         :sort => 3,
       }

data/lib/jsduck/shortener.rb

@@ -0,0 +1,58 @@
+# -*- coding: utf-8 -*-
+require 'jsduck/util/html'
+require 'jsduck/util/singleton'
+
+module JsDuck
+
+  # Little helper for shortening text
+  class Shortener
+    include Util::Singleton
+
+    # Maximum length for text that doesn't get shortened.
+    # The accessor is used for testing purposes only.
+    attr_accessor :max_length
+
+    def initialize
+      @max_length = 120
+    end
+
+    # Shortens text
+    #
+    # 116 chars is also where ext-doc makes its cut, but unlike
+    # ext-doc we only make the cut when there's more than 120 chars.
+    #
+    # This way we don't get stupid expansions like:
+    #
+    #   Blah blah blah some text...
+    #
+    # expanding to:
+    #
+    #   Blah blah blah some text.
+    #
+    def shorten(input)
+      sent = first_sentence(Util::HTML.strip_tags(input).strip)
+      # Use u-modifier to correctly count multi-byte characters
+      chars = sent.scan(/./mu)
+      if chars.length > @max_length
+        chars[0..(@max_length-4)].join + "..."
+      else
+        sent + " ..."
+      end
+    end
+
+    # Returns the first sentence inside a string.
+    def first_sentence(str)
+      str.sub(/\A(.+?(\.|。))\s.*\Z/mu, "\\1")
+    end
+
+    # Returns true when input should get shortened.
+    def too_long?(input)
+      stripped = Util::HTML.strip_tags(input).strip
+      # for sentence v/s full - compare byte length
+      # for full v/s max - compare char length
+      first_sentence(stripped).length < stripped.length || stripped.scan(/./mu).length > @max_length
+    end
+
+  end
+
+end

data/lib/jsduck/signature_renderer.rb

@@ -71,8 +71,7 @@ module JsDuck
     end
 
     def render_single_param(param)
-      p = param[:html_type] + " " + param[:name]
-      param[:optional] ? "["+p+"]" : p
+      param[:optional] ? "["+param[:name]+"]" : param[:name]
     end
 
     def render_return

data/lib/jsduck/source/file.rb

@@ -0,0 +1,98 @@
+require 'jsduck/source/file_parser'
+require 'jsduck/util/html'
+
+module JsDuck
+  module Source
+
+    # Represents one JavaScript or CSS source file.
+    #
+    # The filename parameter determines whether it's parsed as
+    # JavaScript (the default) or CSS.
+    class File
+      attr_reader :filename
+      attr_reader :contents
+      attr_reader :docs
+      attr_reader :html_filename
+
+      def initialize(contents, filename="", options={})
+        @contents = contents
+        @filename = filename
+        @html_filename = ""
+        @links = {}
+
+        @docs = Source::FileParser.new.parse(@contents, @filename, options)
+
+        @docs.map do |docset|
+          link(docset[:linenr], 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.
+      # If doc-object is class, links also the contained cfgs and constructor.
+      # Returns the modified doc-object after done.
+      def link(linenr, doc)
+        @links[linenr] = [] unless @links[linenr]
+        file = {
+          :filename => @filename,
+          :linenr => linenr,
+        }
+        @links[linenr] << {:doc => doc, :file => file}
+        doc[:files] = [file]
+        if doc[:tagname] == :class
+          doc[:members].each {|m| link(linenr, m) }
+        end
+        doc
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/source/file_parser.rb

@@ -0,0 +1,72 @@
+require 'jsduck/js_parser'
+require 'jsduck/css_parser'
+require 'jsduck/doc_parser'
+require 'jsduck/merger'
+require 'jsduck/ast'
+require 'jsduck/doc_type'
+require 'jsduck/doc_ast'
+require 'jsduck/class_doc_expander'
+
+module JsDuck
+  module Source
+
+    # Performs the actual parsing of CSS or JS source.
+    #
+    # This is the class that brings together all the different steps of
+    # parsing the source.
+    class FileParser
+
+      def initialize
+        @doc_type = DocType.new
+        @doc_parser = DocParser.new
+        @class_doc_expander = ClassDocExpander.new
+        @doc_ast = DocAst.new
+        @merger = Merger.new
+      end
+
+      # Parses file into final docset that can be fed into Aggregator
+      def parse(contents, filename="", options={})
+        @doc_ast.filename = filename
+
+        parse_js_or_css(contents, filename, options).map do |docset|
+          expand(docset)
+        end.flatten.map do |docset|
+          merge(docset)
+        end
+      end
+
+      private
+
+      # Parses the file depending on filename as JS or CSS
+      def parse_js_or_css(contents, filename, options)
+        if filename =~ /\.s?css$/
+          docs = CssParser.new(contents, options).parse
+        else
+          docs = JsParser.new(contents, options).parse
+          docs = Ast.new(docs, options).detect_all!
+        end
+      end
+
+      # Parses the docs, detects tagname and expands class docset
+      def expand(docset)
+        docset[:comment] = @doc_parser.parse(docset[:comment])
+        docset[:tagname] = @doc_type.detect(docset[:comment], docset[:code])
+
+        if docset[:tagname] == :class
+          @class_doc_expander.expand(docset)
+        else
+          docset
+        end
+      end
+
+      # Merges comment and code parts of docset
+      def merge(docset)
+        @doc_ast.linenr = docset[:linenr]
+        docset[:comment] = @doc_ast.detect(docset[:tagname], docset[:comment])
+
+        @merger.merge(docset)
+      end
+    end
+
+  end
+end