jsduck 3.1.0 → 3.2.1

data/lib/jsduck/aggregator.rb

@@ -85,15 +85,19 @@ module JsDuck
     # Merges new class-doc into old one.
     def merge_classes(old, new)
       # Merge booleans
-      [:extends, :singleton, :private, :protected].each do |tag|
+      [:extends, :singleton, :private].each do |tag|
         old[tag] = old[tag] || new[tag]
       end
       # Merge arrays
       [:mixins, :alternateClassNames, :files].each do |tag|
         old[tag] = old[tag] + new[tag]
       end
+      # Merge meta hashes
+      new[:meta].each_pair do |name, value|
+        old[:meta][name] = old[:meta][name] || value
+      end
       # Merge hashes of arrays
-      [:aliases, :meta].each do |tag|
+      [:aliases].each do |tag|
         new[tag].each_pair do |key, contents|
           old[tag][key] = (old[tag][key] || []) + contents
         end
@@ -129,7 +133,7 @@ module JsDuck
     end
 
     def add_to_class(cls, member)
-      cls[member[:static] ? :statics : :members][member[:tagname]] << member
+      cls[member[:meta][:static] ? :statics : :members][member[:tagname]] << member
     end
 
     def add_orphan(node)
@@ -182,8 +186,9 @@ module JsDuck
         :alternateClassNames => [],
         :members => Class.default_members_hash,
         :statics => Class.default_members_hash,
+        :aliases => {},
         :meta => {},
-        :files => [{:filename => "", :linenr => 0}],
+        :files => [{:filename => "", :linenr => 0, :href => ""}],
       })
     end
 

data/lib/jsduck/app.rb

@@ -143,6 +143,7 @@ module JsDuck
       class_formatter.include_types = !@opts.export
       # Format all doc-objects in parallel
       formatted_classes = @parallel.map(@relations.classes) do |cls|
+        Logger.instance.log("Markdown formatting #{cls[:name]}")
         {
           :doc => class_formatter.format(cls.internal_doc),
           :images => doc_formatter.images

data/lib/jsduck/app_data.rb

@@ -2,6 +2,7 @@ require 'jsduck/json_duck'
 require 'jsduck/icons'
 require 'jsduck/search_data'
 require 'jsduck/stats'
+require 'jsduck/meta_tag_registry'
 
 module JsDuck
 
@@ -18,13 +19,19 @@ module JsDuck
 
     # Writes classes, guides, videos, and search data to one big .js file
     def write(filename)
-      js = "Docs.data = " + JsonDuck.generate({
-        :classes => Icons.new.create(@relations.classes),
-        :guides => @guides.to_array,
-        :videos => @videos.to_array,
-        :examples => @examples.to_array,
-        :search => SearchData.new.create(@relations.classes),
-        :stats => @opts.stats ? Stats.new.create(@relations.classes) : [],
+      js = "Docs = " + JsonDuck.generate({
+        :data => {
+          :classes => Icons.new.create(@relations.classes),
+          :guides => @guides.to_array,
+          :videos => @videos.to_array,
+          :examples => @examples.to_array,
+          :search => SearchData.new.create(@relations.classes),
+          :stats => @opts.stats ? Stats.new.create(@relations.classes) : [],
+          :signatures => MetaTagRegistry.instance.signatures,
+          :localStorageDb => @opts.local_storage_db,
+          :showPrintButton => @opts.seo,
+          :touchExamplesUi => @opts.touch_examples_ui,
+        }
       }) + ";\n"
       File.open(filename, 'w') {|f| f.write(js) }
     end

data/lib/jsduck/app_exporter.rb

@@ -1,6 +1,7 @@
 require 'jsduck/full_exporter'
 require 'jsduck/renderer'
 require 'jsduck/doc_formatter'
+require 'jsduck/meta_tag_registry'
 
 module JsDuck
 
@@ -12,8 +13,7 @@ module JsDuck
       @renderer = Renderer.new
       # Inject formatter to all meta-tags.
       doc_formatter = DocFormatter.new(relations, opts)
-      opts.meta_tags.each {|tag| tag.formatter = doc_formatter }
-      @renderer.meta_tags = opts.meta_tags
+      MetaTagRegistry.instance.formatter = doc_formatter
     end
 
     # Returns compacted class data hash which contains an additional
@@ -45,7 +45,7 @@ module JsDuck
 
     def compact_member(m)
       m_copy = {}
-      [:name, :tagname, :owner, :protected, :static, :deprecated, :required, :template, :id].each do |key|
+      [:name, :tagname, :owner, :meta, :id].each do |key|
         m_copy[key] = m[key]
       end
       m_copy

data/lib/jsduck/class.rb

@@ -154,25 +154,28 @@ module JsDuck
       local_members
     end
 
-    # Returns member by name.
+    # Returns members by name. An array of one or more members, or
+    # empty array when nothing matches.
     #
     # Optionally one can also specify type name to differenciate
     # between different types of members.
-    def get_member(name, type_name=nil)
+    def get_members(name, type_name=nil, static=false)
       # build hash of all members
       unless @members_map
         @members_map = {}
         [:members, :statics].each do |group|
           @doc[group].each_key do |type|
             members_hash(type, group).each_pair do |key, member|
-              @members_map["#{type}-#{key}"] = member
-              @members_map[key] = member
+              @members_map[key] = (@members_map[key] || []) + [member]
             end
           end
         end
       end
 
-      @members_map[type_name ? "#{type_name}-#{name}" : name]
+      ms = @members_map[name] || []
+      ms = ms.find_all {|m| m[:tagname] == type_name } if type_name
+      ms = ms.find_all {|m| m[:meta][:static] } if static
+      return ms
     end
 
     # Returns all public members of class, including the inherited and mixed in ones

data/lib/jsduck/class_formatter.rb

@@ -14,7 +14,6 @@ module JsDuck
       @relations = relations
       @formatter = formatter
       @include_types = true
-      @meta_tags = []
     end
 
     # Runs the formatter on doc object of a class.
@@ -36,7 +35,6 @@ module JsDuck
     def format_member(m)
       @formatter.doc_context = m[:files][0]
       m[:doc] = @formatter.format(m[:doc]) if m[:doc]
-      m[:deprecated][:text] = @formatter.format(m[:deprecated][:text]) if m[:deprecated]
       if expandable?(m) || @formatter.too_long?(m[:doc])
         m[:shortDoc] = @formatter.shorten(m[:doc])
       end
@@ -52,7 +50,7 @@ module JsDuck
     end
 
     def expandable?(m)
-      m[:params] || (m[:properties] && m[:properties].length > 0) || m[:default] || m[:deprecated] || m[:template]
+      m[:params] || (m[:properties] && m[:properties].length > 0) || m[:default] || m[:meta][:deprecated] || m[:meta][:template]
     end
 
     def format_item(it, is_css_tag)

data/lib/jsduck/css_parser.rb

@@ -6,7 +6,7 @@ module JsDuck
   class CssParser
     def initialize(input, options = {})
       @lex = Lexer.new(input)
-      @doc_parser = DocParser.new(:css, options[:meta_tags])
+      @doc_parser = DocParser.new
       @docs = []
     end
 

data/lib/jsduck/doc_formatter.rb

@@ -78,27 +78,48 @@ module JsDuck
     #
     # Adds 'inline-example' class to code examples beginning with @example.
     #
-    # Additionally replaces strings recognized as ClassNames with
-    # links to these classes.  So one doesn even need to use the @link
-    # tag to create a link.
+    # Additionally replaces strings recognized as ClassNames or
+    # #members with links to these classes or members.  So one doesn't
+    # even need to use the @link tag to create a link.
     def replace(input)
       s = StringScanner.new(input)
       out = ""
+
+      # Keep track of the nesting level of <a> tags. We're not
+      # auto-detecting class names when inside <a>. Normally links
+      # shouldn't be nested, but just to be extra safe.
+      open_a_tags = 0
+
       while !s.eos? do
         if s.check(@link_re)
           out += replace_link_tag(s.scan(@link_re))
         elsif s.check(@img_re)
           out += replace_img_tag(s.scan(@img_re))
+        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 s.check(/[{<]/)
-          out += s.scan(/[{<]/)
+        elsif s.check(/<a\b/)
+          # Increment number of open <a> tags.
+          open_a_tags += 1
+          out += s.scan_until(/>|\Z/)
+        elsif s.check(/<\/a>/)
+          # <a> closed, auto-detection may continue when no more <a> tags open.
+          open_a_tags -= 1
+          out += s.scan(/<\/a>/)
+        elsif s.check(/</)
+          # Ignore all other HTML tags
+          out += s.scan_until(/>|\Z/)
         else
-          out += replace_class_names(s.scan(/[^{<]+/))
+          # 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
@@ -108,12 +129,14 @@ module JsDuck
       input.sub(@link_re) do
         target = $1
         text = $2
-        if target =~ /^(.*)#(?:(.*)-)?(.*)$/
+        if target =~ /^(.*)#(static-)?(?:(cfg|property|method|event|css_var|css_mixin)-)?(.*)$/
           cls = $1.empty? ? @class_context : $1
-          type = $2 ? $2.intern : nil
-          member = $3
+          static = !!$2
+          type = $3 ? $3.intern : nil
+          member = $4
         else
           cls = target
+          static = false
           type = false
           member = false
         end
@@ -131,15 +154,39 @@ module JsDuck
         line = @doc_context[:linenr]
         if !@relations[cls]
           Logger.instance.warn(:link, "#{input} links to non-existing class", file, line)
-          text
-        elsif member && !get_member(cls, member, type)
-          Logger.instance.warn(:link, "#{input} links to non-existing member", file, line)
-          text
-        elsif member && !public_member?(cls, member, type)
-          Logger.instance.warn(:link, "#{input} links to private member", file, line)
-          text
+          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
+
+          ms = ms.find_all {|m| !m[:private] }
+          if ms.length == 0
+            Logger.instance.warn(:link_private, "#{input} links to private 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
-          link(cls, member, text, type)
+          return link(cls, false, text)
         end
       end
     end
@@ -148,21 +195,73 @@ module JsDuck
       input.sub(@img_re) { img($1, $2) }
     end
 
-    def replace_class_names(input)
-      input.gsub(/(\A|\s)([A-Z][A-Za-z0-9.]*[A-Za-z0-9])(?:(#)([A-Za-z0-9]+))?([.,]?(?:\s|\Z))/m) do
-        before = $1
-        cls = $2
-        hash = $3
-        member = $4
-        after = $5
-
-        if @relations[cls] && (member ? public_member?(cls, member) : cls =~ /\./)
-          label = member ? cls+"."+member : cls
-          before + link(cls, member, label) + after
+    # 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
-          before + cls + (hash || "") + (member || "") + after
+          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")
         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])
     end
 
     # applies the image template
@@ -181,11 +280,11 @@ module JsDuck
     end
 
     # applies the link template
-    def link(cls, member, anchor_text, type=nil)
+    def link(cls, member, anchor_text, type=nil, static=false)
       # Use the canonical class name for link (not some alternateClassName)
       cls = @relations[cls].full_name
       # prepend type name to member name
-      member = member && get_member(cls, member, type)
+      member = member && get_matching_member(cls, member, type, static)
 
       @link_tpl.gsub(/(%[\w#-])/) do
         case $1
@@ -205,13 +304,18 @@ module JsDuck
       end
     end
 
-    def public_member?(cls, member, type=nil)
-      m = get_member(cls, member, type)
-      return m && !m[:private]
+    def get_matching_member(cls, member, type=nil, static=false)
+      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_member(cls, member, type=nil)
-      return @relations[cls] && @relations[cls].get_member(member, type)
+    def get_members(cls, member, type=nil, static=false)
+      @relations[cls] ? @relations[cls].get_members(member, type, static) : []
     end
 
     # Formats doc-comment for placement into HTML.

data/lib/jsduck/doc_parser.rb

@@ -1,6 +1,7 @@
 require 'strscan'
 require 'jsduck/js_literal_parser'
 require 'jsduck/js_literal_builder'
+require 'jsduck/meta_tag_registry'
 
 module JsDuck
 
@@ -23,15 +24,10 @@ module JsDuck
   # @see and {@link} are parsed separately in JsDuck::DocFormatter.
   #
   class DocParser
-    # Pass in :css to be able to parse CSS doc-comments
-    def initialize(mode = :js, meta_tags = nil)
-      @ident_pattern = (mode == :css) ? /\$?[\w-]+/ : /[$\w]\w*/
-      @ident_chain_pattern = (mode == :css) ? /\$?[\w-]+(\.[\w-]+)*/ : /[$\w]\w*(\.\w+)*/
-
-      @meta_tags_map = {}
-      (meta_tags || []).each do |tag|
-        @meta_tags_map[tag.name] = tag
-      end
+    def initialize
+      @ident_pattern = /[$\w-]+/
+      @ident_chain_pattern = /[$\w-]+(\.[$\w-]+)*/
+      @meta_tags = MetaTagRegistry.instance
     end
 
     def parse(input)
@@ -134,33 +130,19 @@ module JsDuck
           at_inheritdoc
         elsif look(/@alias/)
           at_alias
-        elsif look(/@deprecated\b/)
-          at_deprecated
         elsif look(/@var\b/)
           at_var
-        elsif look(/@static\b/)
-          boolean_at_tag(/@static/, :static)
         elsif look(/@inheritable\b/)
           boolean_at_tag(/@inheritable/, :inheritable)
         elsif look(/@(private|ignore|hide)\b/)
           boolean_at_tag(/@(private|ignore|hide)/, :private)
-        elsif look(/@protected\b/)
-          boolean_at_tag(/@protected/, :protected)
         elsif look(/@accessor\b/)
           boolean_at_tag(/@accessor/, :accessor)
         elsif look(/@evented\b/)
           boolean_at_tag(/@evented/, :evented)
-        elsif look(/@template\b/)
-          boolean_at_tag(/@template/, :template)
-        elsif look(/@markdown\b/)
-          # this is detected just to be ignored
-          boolean_at_tag(/@markdown/, :markdown)
-        elsif look(/@abstract\b/)
-          # this is detected just to be ignored
-          boolean_at_tag(/@abstract/, :abstract)
         elsif look(/@/)
           @input.scan(/@/)
-          tag = @meta_tags_map[look(/\w+/)]
+          tag = @meta_tags[look(/\w+/)]
           if tag
             meta_at_tag(tag)
           else
@@ -177,13 +159,21 @@ module JsDuck
       prev_tag = @current_tag
 
       add_tag(:meta)
-      @current_tag[:name] = match(/\w+/)
+      @current_tag[:name] = tag.key
+      match(/\w+/)
       skip_horiz_white
 
-      # Fors singleline tags, scan to the end of line and finish the
-      # tag.  For multiline tags we leave the tag open for :doc
-      # addition just like with built-in multiline tags.
-      unless tag.multiline
+      if tag.boolean
+        # For boolean tags, only scan the tag name and switch context
+        # back to previous tag.
+        skip_white
+        @current_tag = prev_tag
+      elsif tag.multiline
+        # For multiline tags we leave the tag open for :doc addition
+        # just like with built-in multiline tags.
+      else
+        # Fors singleline tags, scan to the end of line and finish the
+        # tag.
         @current_tag[:doc] = @input.scan(/.*$/).strip
         skip_white
         @current_tag = prev_tag
@@ -275,7 +265,7 @@ module JsDuck
       match(/@property/)
       add_tag(:property)
       maybe_type
-      maybe_ident_chain(:name)
+      maybe_name_with_default
       skip_white
     end
 
@@ -331,7 +321,7 @@ module JsDuck
       skip_white
     end
 
-    # matches @inheritdoc class.name#type-member
+    # matches @inheritdoc class.name#static-type-member
     def at_inheritdoc
       match(/@inherit[dD]oc|@alias/)
 
@@ -341,8 +331,12 @@ module JsDuck
         @current_tag[:cls] = ident_chain
         if look(/#\w/)
           @input.scan(/#/)
-          if look(/\w+-\w+/)
-            @current_tag[:type] = ident
+          if look(/static-/)
+            @current_tag[:static] = true
+            @input.scan(/static-/)
+          end
+          if look(/(cfg|property|method|event|css_var|css_mixin)-/)
+            @current_tag[:type] = ident.to_sym
             @input.scan(/-/)
           end
           @current_tag[:member] = ident
@@ -351,17 +345,6 @@ module JsDuck
       skip_white
     end
 
-    # matches @deprecated <version> some text ... newline
-    def at_deprecated
-      match(/@deprecated/)
-      add_tag(:deprecated)
-      skip_horiz_white
-      @current_tag[:version] = @input.scan(/[0-9.]+/)
-      skip_horiz_white
-      @current_tag[:text] = @input.scan(/.*$/)
-      skip_white
-    end
-
     # Used to match @private, @ignore, @hide, ...
     def boolean_at_tag(regex, propname)
       match(regex)