jsduck 4.0.1 → 4.1.1

data/lib/jsduck/class_doc_expander.rb

@@ -107,14 +107,9 @@ module JsDuck
       results = []
 
       if docset[:code]
-
         (docset[:code][:members] || []).each do |m|
           results << code_to_docset(m) unless @constructor_found && m[:name] == "constructor"
         end
-
-        (docset[:code][:statics] || []).each do |m|
-          results << code_to_docset(m)
-        end
       end
 
       results

data/lib/jsduck/class_formatter.rb

@@ -1,6 +1,7 @@
 require 'jsduck/type_parser'
 require 'jsduck/logger'
 require 'jsduck/meta_tag_registry'
+require 'jsduck/shortener'
 
 module JsDuck
 
@@ -25,21 +26,24 @@ module JsDuck
       @formatter.class_context = cls[:name]
       @formatter.doc_context = cls[:files][0]
       cls[:doc] = @formatter.format(cls[:doc]) if cls[:doc]
-      [:members, :statics].each do |group|
-        cls[group].each_pair do |type, members|
-          # format all members (except hidden ones)
-          cls[group][type] = members.map {|m| m[:meta][:hide] ? m : format_member(m)  }
-        end
-      end
+      # format all members (except hidden ones)
+      cls[:members] = cls[:members].map {|m| m[:meta][:hide] ? m : format_member(m)  }
       cls[:html_meta] = format_meta_data(cls)
       cls
     end
 
+    # Returns the images detected by doc-formatter
+    def images
+      @formatter.images
+    end
+
+    private
+
     def format_member(m)
       @formatter.doc_context = m[:files][0]
       m[:doc] = @formatter.format(m[:doc]) if m[:doc]
-      if expandable?(m) || @formatter.too_long?(m[:doc])
-        m[:shortDoc] = @formatter.shorten(m[:doc])
+      if expandable?(m) || Shortener.too_long?(m[:doc])
+        m[:shortDoc] = Shortener.shorten(m[:doc])
       end
 
       # We don't validate and format CSS var and mixin type definitions
@@ -72,9 +76,9 @@ module JsDuck
       else
         context = @formatter.doc_context
         if tp.error == :syntax
-          Logger.instance.warn(:type_syntax, "Incorrect type syntax #{type}", context[:filename], context[:linenr])
+          Logger.warn(:type_syntax, "Incorrect type syntax #{type}", context[:filename], context[:linenr])
         else
-          Logger.instance.warn(:type_name, "Unknown type #{type}", context[:filename], context[:linenr])
+          Logger.warn(:type_name, "Unknown type #{type}", context[:filename], context[:linenr])
         end
         type
       end

data/lib/jsduck/class_name.rb

@@ -0,0 +1,23 @@
+module JsDuck
+
+  # Common routines for manipulating class names.
+  class ClassName
+
+    # Given a full class name extracts the "class"-part of the name.
+    #
+    #     ClassName.short("My.package.Foo") --> "Foo"
+    #
+    # Because we try to emulate ext-doc, it's not as simple as just
+    # taking the last part.  See class_spec.rb for details.
+    def self.short(name)
+      parts = name.split(/\./)
+      short = parts.pop
+      while parts.length > 1 && parts.last =~ /^[A-Z]/
+        short = parts.pop + "." + short
+      end
+      short
+    end
+
+  end
+
+end

data/lib/jsduck/class_writer.rb

@@ -1,6 +1,7 @@
-require 'jsduck/parallel_wrap'
+require 'jsduck/util/parallel'
 require 'jsduck/logger'
-require 'jsduck/stdout'
+require 'jsduck/util/json'
+require 'jsduck/util/stdout'
 require 'fileutils'
 
 module JsDuck
@@ -23,22 +24,22 @@ module JsDuck
     private
 
     def write_stdout
-      json = ParallelWrap.map(@relations.classes) {|cls| @exporter.export(cls) }.compact
-      Stdout.instance.add(json)
+      json = Util::Parallel.map(@relations.classes) {|cls| @exporter.export(cls) }.compact
+      Util::Stdout.add(json)
     end
 
     def write_dir(dir, extension)
       FileUtils.mkdir(dir)
-      ParallelWrap.each(@relations.classes) do |cls|
+      Util::Parallel.each(@relations.classes) do |cls|
         filename = dir + "/" + cls[:name] + extension
-        Logger.instance.log("Writing docs", filename)
+        Logger.log("Writing docs", filename)
         json = @exporter.export(cls)
         # skip file if exporter returned nil
         if json
           if extension == ".json"
-            JsonDuck.write_json(filename, json)
+            Util::Json.write_json(filename, json)
           elsif extension == ".js"
-            JsonDuck.write_jsonp(filename, cls[:name].gsub(/\./, "_"), json)
+            Util::Json.write_jsonp(filename, cls[:name].gsub(/\./, "_"), json)
           else
             throw "Unexpected file extension: #{extension}"
           end

data/lib/jsduck/doc_ast.rb

@@ -58,14 +58,13 @@ module JsDuck
 
     def create_method(docs)
       doc_map = build_doc_map(docs)
-      name = detect_name(:method, doc_map)
       return add_shared({
         :tagname => :method,
-        :name => name,
+        :name => detect_name(:method, doc_map),
         :owner => detect_owner(doc_map),
         :doc => detect_doc(docs),
         :params => detect_params(doc_map),
-        :return => detect_return(doc_map, name == "constructor" ? "Object" : "undefined"),
+        :return => detect_return(doc_map),
         :throws => detect_throws(doc_map),
       }, doc_map)
     end
@@ -248,7 +247,7 @@ module JsDuck
             parent[:properties] = [] unless parent[:properties]
             parent[:properties] << it
           else
-            Logger.instance.warn(:subproperty, "Ignoring subproperty #{$1}.#{$2}, no parent found with name '#{$1}'.", @filename, @linenr)
+            Logger.warn(:subproperty, "Ignoring subproperty #{$1}.#{$2}, no parent found with name '#{$1}'.", @filename, @linenr)
           end
         else
           items << it
@@ -257,10 +256,10 @@ module JsDuck
       items
     end
 
-    def detect_return(doc_map, default_type="undefined")
+    def detect_return(doc_map)
       ret = extract(doc_map, :return) || {}
       return {
-        :type => ret[:type] || default_type,
+        :type => ret[:type] || "undefined",
         :name => ret[:name] || "return",
         :doc => ret[:doc] || "",
         :properties => doc_map[:return] ? detect_subproperties(:return, doc_map[:return]) : []

data/lib/jsduck/doc_formatter.rb

@@ -1,71 +1,80 @@
-# -*- coding: utf-8 -*-
 require 'rubygems'
 require 'strscan'
 require 'rdiscount'
-require 'jsduck/logger'
-require 'jsduck/inline_img'
-require 'jsduck/inline_video'
-require 'jsduck/html'
+require 'jsduck/inline/link'
+require 'jsduck/inline/img'
+require 'jsduck/inline/video'
+require 'jsduck/inline/example'
 
 module JsDuck
 
   # Formats doc-comments
   class DocFormatter
-    # Template HTML that replaces {@link Class#member anchor text}.
-    # Can contain placeholders:
-    #
-    # %c - full class name (e.g. "Ext.Panel")
-    # %m - class member name prefixed with member type (e.g. "method-urlEncode")
-    # %# - inserts "#" if member name present
-    # %- - inserts "-" if member name present
-    # %a - anchor text for link
-    #
-    # Default value: '<a href="%c%M">%a</a>'
-    attr_accessor :link_tpl
+
+    # Creates a formatter configured with options originating from
+    # command line.  For the actual effect of the options see
+    # Inline::* classes.
+    def initialize(opts={})
+      @inline_link = Inline::Link.new(opts)
+      @inline_img = Inline::Img.new(opts)
+      @inline_video = Inline::Video.new(opts)
+      @inline_example = Inline::Example.new(opts)
+    end
+
+    # Sets base path to prefix images from {@img} tags.
+    def img_path=(path)
+      @inline_img.base_path = path
+    end
+
+    # Returns list of all image paths gathered from {@img} tags.
+    def images
+      @inline_img.images
+    end
 
     # Sets up instance to work in context of particular class, so
     # that when {@link #blah} is encountered it knows that
     # Context#blah is meant.
-    attr_accessor :class_context
+    def class_context=(cls)
+      @inline_link.class_context = cls
+    end
 
     # Sets up instance to work in context of particular doc object.
     # Used for error reporting.
-    attr_accessor :doc_context
+    def doc_context=(doc)
+      @inline_video.doc_context = doc
+      @inline_link.doc_context = doc
+    end
 
-    # Maximum length for text that doesn't get shortened, defaults to 120
-    attr_accessor :max_length
+    # Returns the current documentation context
+    def doc_context
+      @inline_link.doc_context
+    end
 
     # JsDuck::Relations for looking up class names.
     #
     # When auto-creating class links from CamelCased names found from
     # text, we check the relations object to see if a class with that
     # name actually exists.
-    attr_accessor :relations
-
-    def initialize(relations={}, opts={})
-      @class_context = ""
-      @doc_context = {}
-      @max_length = 120
-      @relations = relations
-      @images = []
-
-      @inline_img = InlineImg.new(opts)
-      @inline_video = InlineVideo.new(opts)
-
-      @link_tpl = opts[:link_tpl] || '<a href="%c%#%m">%a</a>'
-      @link_re = /\{@link\s+(\S*?)(?:\s+(.+?))?\}/m
-
-      @example_annotation_re = /<pre><code>\s*@example( +[^\n]*)?\s+/m
+    def relations=(relations)
+      @inline_link.relations = relations
     end
 
-    # Sets base path to prefix images from {@img} tags.
-    def img_path=(path)
-      @inline_img.base_path = path
-    end
+    # Formats doc-comment for placement into HTML.
+    # Renders it with Markdown-formatter and replaces @link-s.
+    def format(input)
+      # In ExtJS source "<pre>" is often at the end of paragraph, not
+      # on its own line.  But in that case RDiscount doesn't recognize
+      # it as the beginning of <pre>-block and goes on parsing it as
+      # normal Markdown, which often causes nested <pre>-blocks.
+      #
+      # To prevent this, we always add extra newline before <pre>.
+      input.gsub!(/([^\n])<pre>/, "\\1\n<pre>")
 
-    # Returns list of all image paths gathered from {@img} tags.
-    def images
-      @inline_img.images
+      # But we remove trailing newline after <pre> to prevent
+      # code-blocks beginning with empty line.
+      input.gsub!(/<pre>(<code>)?\n?/, "<pre>\\1")
+
+      replace(RDiscount.new(input).to_html)
     end
 
     # Replaces {@link} and {@img} tags, auto-generates links for
@@ -91,21 +100,17 @@ module JsDuck
       open_a_tags = 0
 
       while !s.eos? do
-        if s.check(@link_re)
-          out += replace_link_tag(s.scan(@link_re))
+        if substitute = @inline_link.replace(s)
+          out += substitute
         elsif substitute = @inline_img.replace(s)
           out += substitute
-        elsif substitute = @inline_video.replace(s, @doc_context)
+        elsif substitute = @inline_video.replace(s)
           out += substitute
         elsif s.check(/[{]/)
           # There might still be "{" that doesn't begin {@link} or {@img} - ignore it
           out += s.scan(/[{]/)
-        elsif s.check(@example_annotation_re)
-          # Match possible classnames following @example and add them
-          # as CSS classes inside <pre> element.
-          s.scan(@example_annotation_re) =~ @example_annotation_re
-          css_classes = ($1 || "").strip
-          out += "<pre class='inline-example #{css_classes}'><code>"
+        elsif substitute = @inline_example.replace(s)
+          out += substitute
         elsif s.check(/<a\b/)
           # Increment number of open <a> tags.
           open_a_tags += 1
@@ -121,232 +126,16 @@ module JsDuck
           # Replace class names in the following text up to next "<" or "{"
           # but only when we're not inside <a>...</a>
           text = s.scan(/[^{<]+/)
-          out += open_a_tags > 0 ? text : create_magic_links(text)
-        end
-      end
-      out
-    end
-
-    def replace_link_tag(input)
-      input.sub(@link_re) do
-        target = $1
-        text = $2
-        if target =~ /^(.*)#(static-)?(?:(cfg|property|method|event|css_var|css_mixin)-)?(.*)$/
-          cls = $1.empty? ? @class_context : $1
-          static = $2 ? true : nil
-          type = $3 ? $3.intern : nil
-          member = $4
-        else
-          cls = target
-          static = nil
-          type = false
-          member = false
-        end
-
-        # Construct link text
-        if text
-          text = text
-        elsif member
-          text = (cls == @class_context) ? member : (cls + "." + member)
-        else
-          text = cls
-        end
-
-        file = @doc_context[:filename]
-        line = @doc_context[:linenr]
-        if !@relations[cls]
-          Logger.instance.warn(:link, "#{input} links to non-existing class", file, line)
-          return text
-        elsif member
-          ms = get_members(cls, member, type, static)
-          if ms.length == 0
-            Logger.instance.warn(:link, "#{input} links to non-existing member", file, line)
-            return text
-          end
-
-          if ms.length > 1
-            # When multiple public members, see if there remains just
-            # one when we ignore the static members. If there's more,
-            # report ambiguity. If there's only static members, also
-            # report ambiguity.
-            instance_ms = ms.find_all {|m| !m[:meta][:static] }
-            if instance_ms.length > 1
-              alternatives = instance_ms.map {|m| m[:tagname].to_s }.join(", ")
-              Logger.instance.warn(:link_ambiguous, "#{input} is ambiguous: "+alternatives, file, line)
-            elsif instance_ms.length == 0
-              static_ms = ms.find_all {|m| m[:meta][:static] }
-              alternatives = static_ms.map {|m| "static " + m[:tagname].to_s }.join(", ")
-              Logger.instance.warn(:link_ambiguous, "#{input} is ambiguous: "+alternatives, file, line)
-            end
-          end
-
-          return link(cls, member, text, type, static)
-        else
-          return link(cls, false, text)
-        end
-      end
-    end
-
-    # Looks input text for patterns like:
-    #
-    #  My.ClassName
-    #  MyClass#method
-    #  #someProperty
-    #
-    # and converts them to links, as if they were surrounded with
-    # {@link} tag. One notable exception is that Foo is not created to
-    # link, even when Foo class exists, but Foo.Bar is. This is to
-    # avoid turning normal words into links. For example:
-    #
-    #     Math involves a lot of numbers. Ext JS is a JavaScript framework.
-    #
-    # In these sentences we don't want to link "Math" and "Ext" to the
-    # corresponding JS classes.  And that's why we auto-link only
-    # class names containing a dot "."
-    #
-    def create_magic_links(input)
-      cls_re = "([A-Z][A-Za-z0-9.]*[A-Za-z0-9])"
-      member_re = "(?:#([A-Za-z0-9]+))"
-
-      input.gsub(/\b#{cls_re}#{member_re}?\b|#{member_re}\b/m) do
-        replace_magic_link($1, $2 || $3)
-      end
-    end
-
-    def replace_magic_link(cls, member)
-      if cls && member
-        if @relations[cls] && get_matching_member(cls, member)
-          return link(cls, member, cls+"."+member)
-        else
-          warn_magic_link("#{cls}##{member} links to non-existing " + (@relations[cls] ? "member" : "class"))
-        end
-      elsif cls && cls =~ /\./
-        if @relations[cls]
-          return link(cls, nil, cls)
-        else
-          cls2, member2 = split_to_cls_and_member(cls)
-          if @relations[cls2] && get_matching_member(cls2, member2)
-            return link(cls2, member2, cls2+"."+member2)
-          elsif cls =~ /\.(js|css|html|php)\Z/
-            # Ignore common filenames
-          else
-            warn_magic_link("#{cls} links to non-existing class")
-          end
-        end
-      elsif !cls && member
-        if get_matching_member(@class_context, member)
-          return link(@class_context, member, member)
-        elsif member =~ /\A([A-F0-9]{3}|[A-F0-9]{6})\Z/i || member =~ /\A[0-9]/
-          # Ignore HEX color codes and
-          # member names beginning with number
-        else
-          warn_magic_link("##{member} links to non-existing member")
+          out += open_a_tags > 0 ? text : @inline_link.create_magic_links(text)
         end
       end
 
-      return "#{cls}#{member ? '#' : ''}#{member}"
-    end
-
-    def split_to_cls_and_member(str)
-      parts = str.split(/\./)
-      return [parts.slice(0, parts.length-1).join("."), parts.last]
-    end
-
-    def warn_magic_link(msg)
-      Logger.instance.warn(:link_auto, msg, @doc_context[:filename], @doc_context[:linenr])
+      out
     end
 
-    # applies the link template
+    # Creates a link based on the link template.
     def link(cls, member, anchor_text, type=nil, static=nil)
-      # Use the canonical class name for link (not some alternateClassName)
-      cls = @relations[cls].full_name
-      # prepend type name to member name
-      member = member && get_matching_member(cls, member, type, static)
-
-      @link_tpl.gsub(/(%[\w#-])/) do
-        case $1
-        when '%c'
-          cls
-        when '%m'
-          member ? member[:id] : ""
-        when '%#'
-          member ? "#" : ""
-        when '%-'
-          member ? "-" : ""
-        when '%a'
-          HTML.escape(anchor_text||"")
-        else
-          $1
-        end
-      end
-    end
-
-    def get_matching_member(cls, member, type=nil, static=nil)
-      ms = get_members(cls, member, type, static).find_all {|m| !m[:private] }
-      if ms.length > 1
-        instance_ms = ms.find_all {|m| !m[:meta][:static] }
-        instance_ms.length > 0 ? instance_ms[0] : ms.find_all {|m| m[:meta][:static] }[0]
-      else
-        ms[0]
-      end
-    end
-
-    def get_members(cls, member, type=nil, static=nil)
-      @relations[cls] ? @relations[cls].get_members(member, type, static) : []
-    end
-
-    # Formats doc-comment for placement into HTML.
-    # Renders it with Markdown-formatter and replaces @link-s.
-    def format(input)
-      # In ExtJS source "<pre>" is often at the end of paragraph, not
-      # on its own line.  But in that case RDiscount doesn't recognize
-      # it as the beginning of <pre>-block and goes on parsing it as
-      # normal Markdown, which often causes nested <pre>-blocks.
-      #
-      # To prevent this, we always add extra newline before <pre>.
-      input.gsub!(/([^\n])<pre>/, "\\1\n<pre>")
-
-      # But we remove trailing newline after <pre> to prevent
-      # code-blocks beginning with empty line.
-      input.gsub!(/<pre>(<code>)?\n?/, "<pre>\\1")
-
-      replace(RDiscount.new(input).to_html)
-    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(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
-
-    def first_sentence(str)
-      str.sub(/\A(.+?(\.|。))\s.*\Z/mu, "\\1")
-    end
-
-    # Returns true when input should get shortened.
-    def too_long?(input)
-      stripped = 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
+      @inline_link.link(cls, member, anchor_text, type, static)
     end
 
   end