jsduck 3.11.2 → 4.0.beta

data/lib/jsduck/doc_parser.rb

@@ -1,6 +1,4 @@
 require 'strscan'
-require 'jsduck/js_literal_parser'
-require 'jsduck/js_literal_builder'
 require 'jsduck/meta_tag_registry'
 
 module JsDuck
@@ -50,9 +48,7 @@ module JsDuck
     # Extracts content inside /** ... */
     def purify(input)
       result = []
-      # Remove the beginning /** and end */
-      input = input.sub(/\A\/\*\* ?/, "").sub(/ ?\*\/\Z/, "")
-      # Now we are left with only two types of lines:
+      # We can have two types of lines:
       # - those beginning with *
       # - and those without it
       indent = nil
@@ -141,7 +137,7 @@ module JsDuck
         elsif look(/@evented\b/)
           boolean_at_tag(/@evented/, :evented)
         elsif look(/@/)
-          @input.scan(/@/)
+          match(/@/)
           tag = @meta_tags[look(/\w+/)]
           if tag
             meta_at_tag(tag)
@@ -149,7 +145,7 @@ module JsDuck
             @current_tag[:doc] += "@"
           end
         elsif look(/[^@]/)
-          @current_tag[:doc] += @input.scan(/[^@]+/)
+          @current_tag[:doc] += match(/[^@]+/)
         end
       end
     end
@@ -174,7 +170,7 @@ module JsDuck
       else
         # Fors singleline tags, scan to the end of line and finish the
         # tag.
-        @current_tag[:doc] = @input.scan(/.*$/).strip
+        @current_tag[:doc] = match(/.*$/).strip
         skip_white
         @current_tag = prev_tag
       end
@@ -300,7 +296,7 @@ module JsDuck
         @current_tag[:type] = tdf[:type]
         @current_tag[:optional] = true if tdf[:optional]
       elsif look(/\S/)
-        @current_tag[:type] = @input.scan(/\S+/)
+        @current_tag[:type] = match(/\S+/)
       end
       skip_white
     end
@@ -343,14 +339,14 @@ module JsDuck
       end
 
       if look(/#\w/)
-        @input.scan(/#/)
+        match(/#/)
         if look(/static-/)
           @current_tag[:static] = true
-          @input.scan(/static-/)
+          match(/static-/)
         end
         if look(/(cfg|property|method|event|css_var|css_mixin)-/)
           @current_tag[:type] = ident.to_sym
-          @input.scan(/-/)
+          match(/-/)
         end
         @current_tag[:member] = ident
       end
@@ -418,7 +414,7 @@ module JsDuck
     def maybe_name
       skip_horiz_white
       if look(@ident_pattern)
-        @current_tag[:name] = @input.scan(@ident_pattern)
+        @current_tag[:name] = match(@ident_pattern)
       end
     end
 
@@ -430,17 +426,15 @@ module JsDuck
       end
     end
 
-    # attempts to match javascript literal,
-    # when it fails grabs anything up to closing "]"
+    # Attempts to allow balanced braces in default value.
+    # When the nested parsing doesn't finish at closing "]",
+    # roll back to beginning and simply grab anything up to closing "]".
     def default_value
       start_pos = @input.pos
-      lit = JsLiteralParser.new(@input).literal
-      if lit && look(/ *\]/)
-        # When lital matched and there's nothing after it up to the closing "]"
-        JsLiteralBuilder.new.to_s(lit)
+      value = parse_balanced(/\[/, /\]/, /[^\[\]]*/)
+      if look(/\]/)
+        value
       else
-        # Otherwise reset parsing position to where we started
-        # and rescan up to "]" using simple regex.
         @input.pos = start_pos
         match(/[^\]]*/)
       end
@@ -449,14 +443,8 @@ module JsDuck
     # matches {...=} and returns text inside brackets
     def typedef
       match(/\{/)
-      name = @input.scan(/[^{}]*/)
 
-      # Type definition can contain nested braces: {{foo:Number}}
-      # In such case we parse the definition so that the braces are balanced.
-      while @input.check(/[{]/)
-        name += "{" + typedef[:type] +"}"
-        name += @input.scan(/[^{}]*/)
-      end
+      name = parse_balanced(/\{/, /\}/, /[^{}]*/)
 
       if name =~ /=$/
         name = name.chop
@@ -470,6 +458,23 @@ module JsDuck
       return {:type => name, :optional => optional}
     end
 
+    # Helper method to parse a string up to a closing brace,
+    # balancing opening-closing braces in between.
+    #
+    # @param re_open  The beginning brace regex
+    # @param re_close The closing brace regex
+    # @param re_rest  Regex to match text without any braces
+    def parse_balanced(re_open, re_close, re_rest)
+      result = match(re_rest)
+      while look(re_open)
+        result += match(re_open)
+        result += parse_balanced(re_open, re_close, re_rest)
+        result += match(re_close)
+        result += match(re_rest)
+      end
+      result
+    end
+
     # matches <ident_chain> <ident_chain> ... until line end
     def class_list
       skip_horiz_white

data/lib/jsduck/doc_type.rb

@@ -0,0 +1,58 @@
+module JsDuck
+
+  # Detects the type of documentation object: class, method, cfg, etc
+  class DocType
+    # Given parsed documentation and code, returns the tagname for
+    # documentation item.
+    #
+    # @param docs Result from DocParser
+    # @param code Result from Ast#detect or CssParser#parse
+    # @returns One of: :class, :method, :event, :cfg, :property, :css_var, :css_mixin
+    #
+    def detect(docs, code)
+      doc_map = build_doc_map(docs)
+
+      if doc_map[:class]
+        :class
+      elsif doc_map[:event]
+        :event
+      elsif doc_map[:method]
+        :method
+      elsif doc_map[:property] || doc_map[:type]
+        :property
+      elsif doc_map[:css_var]
+        :css_var
+      elsif doc_map[:cfg] && doc_map[:cfg].length == 1
+        # When just one @cfg, avoid treating it as @class
+        :cfg
+      elsif code[:tagname] == :class
+        :class
+      elsif code[:tagname] == :css_mixin
+        :css_mixin
+      elsif doc_map[:cfg]
+        :cfg
+      elsif doc_map[:constructor]
+        :method
+      else
+        code[:tagname]
+      end
+    end
+
+    private
+
+    # Build map of at-tags for quick lookup
+    def build_doc_map(docs)
+      map = {}
+      docs.each do |tag|
+        if map[tag[:tagname]]
+          map[tag[:tagname]] << tag
+        else
+          map[tag[:tagname]] = [tag]
+        end
+      end
+      map
+    end
+  end
+
+end
+

data/lib/jsduck/esprima.rb

@@ -0,0 +1,32 @@
+require 'execjs'
+require 'json'
+require 'singleton'
+
+module JsDuck
+
+  # Runs Esprima.js through execjs (this will select any available
+  # JavaScript runtime - preferably therubyracer on MRI and JScript
+  # on Windows).
+  #
+  # Initialized as singleton to avoid loading the esprima.js more
+  # than once - otherwise performace will severely suffer.
+  class Esprima
+    include Singleton
+
+    def initialize
+      esprima_path = File.dirname(File.dirname(File.dirname(File.expand_path(__FILE__))))+"/esprima/esprima.js";
+      esprima = IO.read(esprima_path)
+      helper = "function runEsprima(js) { return JSON.stringify(esprima.parse(js, {comment: true, range: true, raw: true})); }"
+      @context = ExecJS.compile(esprima + "\n\n" + helper)
+    end
+
+    # Parses JavaScript source code using Esprima.js
+    #
+    # Returns the resulting AST
+    def parse(input)
+      json = @context.call("runEsprima", input)
+      return JSON.parse(json, :max_nesting => false)
+    end
+
+  end
+end

data/lib/jsduck/evaluator.rb

@@ -0,0 +1,69 @@
+module JsDuck
+
+  # Evaluates Esprima AST node into Ruby object
+  class Evaluator
+
+    # Converts AST node into a value.
+    #
+    # - String literals become Ruby strings
+    # - Number literals become Ruby numbers
+    # - Regex literals become :regexp symbols
+    # - Array expressions become Ruby arrays
+    # - etc
+    #
+    # For anything it doesn't know how to evaluate (like a function
+    # expression) it throws exception.
+    #
+    def to_value(ast)
+      case ast["type"]
+      when "ArrayExpression"
+        ast["elements"].map {|e| to_value(e) }
+      when "ObjectExpression"
+        h = {}
+        ast["properties"].each do |p|
+          key = key_value(p["key"])
+          value = to_value(p["value"])
+          h[key] = value
+        end
+        h
+      when "BinaryExpression"
+        if ast["operator"] == "+"
+          to_value(ast["left"]) + to_value(ast["right"])
+        else
+          throw "Unable to handle operator: " + ast["operator"]
+        end
+      when "MemberExpression"
+        if base_css_prefix?(ast)
+          "x-"
+        else
+          throw "Unable to handle this MemberExpression"
+        end
+      when "Literal"
+        if ast["raw"] =~ /\A\//
+          :regexp
+        else
+          ast["value"]
+        end
+      else
+        throw "Unknown node type: " + ast["type"]
+      end
+    end
+
+    # Turns object property key into string value
+    def key_value(key)
+      key["type"] == "Identifier" ? key["name"] : key["value"]
+    end
+
+    # True when MemberExpression == Ext.baseCSSPrefix
+    def base_css_prefix?(ast)
+      ast["computed"] == false &&
+        ast["object"]["type"] == "Identifier" &&
+        ast["object"]["name"] == "Ext" &&
+        ast["property"]["type"] == "Identifier" &&
+        ast["property"]["name"] == "baseCSSPrefix"
+    end
+
+  end
+
+end
+

data/lib/jsduck/guides.rb

@@ -36,13 +36,15 @@ module JsDuck
     end
 
     # Modified each_item that also loads HTML for each guide
-    def each_item
-      super do |guide|
-        # Load the guide if not loaded
-        guide[:html] = load_guide(guide) if guide[:html] == nil
-        # Pass guide to block if it was successfully loaded.
-        yield guide if guide[:html]
+    def each_item(&block)
+      unless @loaded
+        super do |guide|
+          guide[:html] = load_guide(guide)
+        end
+        @loaded = true
       end
+
+      super(&block)
     end
 
     # Modified to_array that excludes the :html from guide nodes
@@ -58,13 +60,12 @@ module JsDuck
     def load_guide(guide)
       in_dir = @path + "/guides/" + guide["name"]
 
-      return Logger.instance.warn(:guide, "Guide #{in_dir} not found") unless File.exists?(in_dir)
-
-      guide_file = in_dir + "/README.md"
+      begin
+        return Logger.instance.warn(:guide, "Guide #{in_dir} not found") unless File.exists?(in_dir)
 
-      return Logger.instance.warn(:guide, "README.md not found in #{in_dir}") unless File.exists?(guide_file)
+        guide_file = in_dir + "/README.md"
+        return Logger.instance.warn(:guide, "README.md not found in #{in_dir}") unless File.exists?(guide_file)
 
-      begin
         @formatter.doc_context = {:filename => guide_file, :linenr => 0}
         name = File.basename(in_dir)
         @formatter.img_path = "guides/#{name}"

data/lib/jsduck/inherit_doc.rb

@@ -13,20 +13,54 @@ module JsDuck
     def resolve_all
       @relations.each do |cls|
         resolve_class(cls) if cls[:inheritdoc]
+
+        new_cfgs = []
         cls.all_local_members.each do |member|
-          if member[:inheritdoc]
-            resolve(member)
+          if member[:inheritdoc] || member[:autodetected]
+            resolve(member, new_cfgs)
           end
         end
+        move_cfgs(cls, new_cfgs)
       end
     end
 
+    private
+
     # Copy over doc/params/return from parent member.
-    def resolve(m)
+    def resolve(m, new_cfgs)
       parent = find_parent(m)
-      m[:doc] = (m[:doc] + "\n\n" + parent[:doc]).strip
-      m[:params] = parent[:params] if parent[:params]
-      m[:return] = parent[:return] if parent[:return]
+
+      if m[:inheritdoc] && parent
+        m[:doc] = (m[:doc] + "\n\n" + parent[:doc]).strip
+        m[:params] = parent[:params] if parent[:params]
+        m[:return] = parent[:return] if parent[:return]
+
+        # remember properties that have changed to configs
+        if m[:tagname] != parent[:tagname]
+          new_cfgs << m
+        end
+      end
+
+      resolve_visibility(m, parent)
+    end
+
+    # Changes given properties into configs within class
+    def move_cfgs(cls, members)
+      members.each do |m|
+        m[:tagname] = :cfg
+        cls[:members][:property].delete(m)
+        cls[:members][:cfg] << m
+      end
+    end
+
+    # For auto-detected members/classes (which have @private == :inherit)
+    # Use the visibility from parent class (defaulting to private when no parent).
+    def resolve_visibility(m, parent)
+      if m[:autodetected]
+        if !parent || parent[:private]
+          m[:meta][:private] = m[:private] = true
+        end
+      end
     end
 
     # Finds parent member of the given member.  When @inheritdoc names
@@ -34,7 +68,8 @@ module JsDuck
     #
     # If the parent also has @inheritdoc, continues recursively.
     def find_parent(m)
-      if m[:inheritdoc][:cls]
+      inherit = m[:inheritdoc] || {}
+      if inherit[:cls]
         # @inheritdoc MyClass#member
         parent_cls = @relations[m[:inheritdoc][:cls]]
         return warn("class not found", m) unless parent_cls
@@ -42,7 +77,7 @@ module JsDuck
         parent = lookup_member(parent_cls, m)
         return warn("member not found", m) unless parent
 
-      elsif m[:inheritdoc][:member]
+      elsif inherit[:member]
         # @inheritdoc #member
         parent = lookup_member(@relations[m[:owner]], m)
         return warn("member not found", m) unless parent
@@ -53,7 +88,10 @@ module JsDuck
         mixins = @relations[m[:owner]].mixins
 
         # Warn when no parent or mixins at all
-        return warn("parent class not found", m) unless parent_cls || mixins.length > 0
+        if !parent_cls && mixins.length == 0
+          warn("parent class not found", m) unless m[:autodetected]
+          return nil
+        end
 
         # First check for the member in all mixins, because members
         # from mixins override those from parent class.  Looking first
@@ -69,21 +107,49 @@ module JsDuck
         end
 
         # Only when both parent and mixins fail, throw warning
-        return warn("parent member not found", m) unless parent
+        if !parent
+          warn("parent member not found", m) unless m[:autodetected]
+          return nil
+        end
       end
 
       return parent[:inheritdoc] ? find_parent(parent) : parent
     end
 
     def lookup_member(cls, m)
-      inherit = m[:inheritdoc]
-      cls.get_members(inherit[:member] || m[:name], inherit[:type] || m[:tagname], inherit[:static] || m[:meta][:static])[0]
+      inherit = m[:inheritdoc] || {}
+      name = inherit[:member] || m[:name]
+      tagname = inherit[:type] || m[:tagname]
+      static = inherit[:static] || m[:meta][:static]
+
+      # Auto-detected properties can override either a property or a
+      # config. So look for both types.
+      if m[:autodetected] && tagname == :property
+        cfg = cls.get_members(name, :cfg, static)[0]
+        prop = cls.get_members(name, :property, static)[0]
+
+        if cfg && prop
+          prop
+        elsif cfg
+          cfg
+        elsif prop
+          prop
+        else
+          nil
+        end
+
+      else
+        cls.get_members(name, tagname, static)[0]
+      end
     end
 
     # Copy over doc from parent class.
     def resolve_class(cls)
       parent = find_class_parent(cls)
-      cls[:doc] = (cls[:doc] + "\n\n" + parent[:doc]).strip
+
+      if parent
+        cls[:doc] = (cls[:doc] + "\n\n" + parent[:doc]).strip
+      end
     end
 
     def find_class_parent(cls)
@@ -107,7 +173,7 @@ module JsDuck
       msg = "@inheritdoc #{item[:inheritdoc][:cls]}"+ (i_member ? "#" + i_member : "") + " - " + msg
       Logger.instance.warn(:inheritdoc, msg, context[:filename], context[:linenr])
 
-      return item
+      return nil
     end
 
   end