jsduck 4.0.beta → 4.0.beta2

data/lib/jsduck/ast.rb

@@ -73,7 +73,7 @@ module JsDuck
 
       # Foo = ...
       elsif exp && assignment?(exp) && class_name?(to_s(exp["left"]))
-        make_class(to_s(exp["left"]))
+        make_class(to_s(exp["left"]), exp["right"])
 
       # var foo = Ext.extend("Parent", {})
       elsif var && var["init"] && ext_extend?(var["init"])
@@ -81,7 +81,7 @@ module JsDuck
 
       # var Foo = ...
       elsif var && class_name?(to_s(var["id"]))
-        make_class(to_s(var["id"]))
+        make_class(to_s(var["id"]), var["right"])
 
       # function Foo() {}
       elsif function?(ast) && class_name?(to_s(ast["id"]))
@@ -193,12 +193,20 @@ module JsDuck
         :name => name,
       }
 
-      # apply information from Ext.extend or Ext.define
+      # apply information from Ext.extend, Ext.define, or {}
       if ast
         if ext_extend?(ast)
-          cls[:extends] = to_s(ast["arguments"][0])
+          args = ast["arguments"]
+          cls[:extends] = to_s(args[0])
+          if args.length == 2 && args[1]["type"] == "ObjectExpression"
+            detect_class_members_from_object(cls, args[1])
+          end
         elsif ext_define?(ast)
           detect_ext_define(cls, ast)
+        elsif ast["type"] == "ObjectExpression"
+          detect_class_members_from_object(cls, ast)
+        elsif ast["type"] == "ArrayExpression"
+          detect_class_members_from_array(cls, ast)
         end
       end
 
@@ -217,6 +225,7 @@ module JsDuck
       cls[:aliases] = []
       cls[:members] = []
       cls[:statics] = []
+      cls[:code_type] = :ext_define
 
       each_pair_in_object_expression(ast["arguments"][1]) do |key, value, pair|
         case key
@@ -247,17 +256,38 @@ module JsDuck
         when "inheritableStatics"
           cls[:statics] += make_statics(value, {:inheritable => true})
         else
-          if function?(value)
-            m = make_method(key, value)
-            cls[:members] << m if apply_autodetected(m, pair)
-          else
-            p = make_property(key, value)
-            cls[:members] << p if apply_autodetected(p, pair)
-          end
+          detect_method_or_property(cls, key, value, pair)
         end
       end
     end
 
+    # Detects class members from object literal
+    def detect_class_members_from_object(cls, ast)
+      cls[:members] = []
+      each_pair_in_object_expression(ast) do |key, value, pair|
+        detect_method_or_property(cls, key, value, pair)
+      end
+    end
+
+    # Detects class members from array literal
+    def detect_class_members_from_array(cls, ast)
+      cls[:members] = []
+      ast["elements"].each do |el|
+        detect_method_or_property(cls, key_value(el), el, el)
+      end
+    end
+
+    # Detects item in object literal either as method or property
+    def detect_method_or_property(cls, key, value, pair)
+      if function?(value)
+        m = make_method(key, value)
+        cls[:members] << m if apply_autodetected(m, pair)
+      else
+        p = make_property(key, value)
+        cls[:members] << p if apply_autodetected(p, pair)
+      end
+    end
+
     def make_extends(cfg_value)
       return nil unless cfg_value
 
@@ -325,8 +355,8 @@ module JsDuck
     # returns false.
     #
     # Otherwise detects the line number of member and returns true.
-    def apply_autodetected(m, pair, inheritable=true)
-      docset = find_docset(pair)
+    def apply_autodetected(m, ast, inheritable=true)
+      docset = find_docset(ast)
 
       if !docset || docset[:type] != :doc_comment
         if inheritable
@@ -344,7 +374,7 @@ module JsDuck
         # Get line number from third place at range array.
         # This third item exists in forked EsprimaJS at
         # https://github.com/nene/esprima/tree/linenr-in-range
-        m[:linenr] = pair["range"][2]
+        m[:linenr] = ast["range"][2]
         return true
       end
     end

data/lib/jsduck/class.rb

@@ -239,7 +239,11 @@ module JsDuck
     #
     # Optionally one can also specify type name to differenciate
     # between different types of members.
-    def get_members(name, type_name=nil, static=false)
+    #
+    # Finally static flag can be specified. True to look only at
+    # static members, false to look at instance members, and nil to
+    # look at both.
+    def get_members(name, type_name=nil, static=nil)
       # build hash of all members
       unless @members_map
         @members_map = {}
@@ -254,7 +258,9 @@ module JsDuck
 
       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
+      # static = true | false | nil
+      ms = ms.find_all {|m| m[:meta][:static] } if static == true
+      ms = ms.find_all {|m| !m[:meta][:static] } if static == false
       return ms
     end
 

data/lib/jsduck/class_writer.rb

@@ -10,7 +10,6 @@ module JsDuck
     def initialize(exporter_class, relations, opts)
       @relations = relations
       @exporter = exporter_class.new(relations, opts)
-      @parallel = ParallelWrap.new(:in_processes => opts.processes)
     end
 
     # Writes class data into given directory or STDOUT when dir == :stdout.
@@ -24,13 +23,13 @@ module JsDuck
     private
 
     def write_stdout
-      json = @parallel.map(@relations.classes) {|cls| @exporter.export(cls) }.compact
+      json = ParallelWrap.map(@relations.classes) {|cls| @exporter.export(cls) }.compact
       Stdout.instance.add(json)
     end
 
     def write_dir(dir, extension)
       FileUtils.mkdir(dir)
-      @parallel.each(@relations.classes) do |cls|
+      ParallelWrap.each(@relations.classes) do |cls|
         filename = dir + "/" + cls[:name] + extension
         Logger.instance.log("Writing docs", filename)
         json = @exporter.export(cls)

data/lib/jsduck/doc_ast.rb

@@ -51,6 +51,7 @@ module JsDuck
         :singleton => !!doc_map[:singleton],
         :requires => detect_list(:requires, doc_map),
         :uses => detect_list(:uses, doc_map),
+        :enum => detect_enum(doc_map),
       }, doc_map)
     end
 
@@ -276,6 +277,15 @@ module JsDuck
       end
     end
 
+    def detect_enum(doc_map)
+      return nil unless extract(doc_map, :class, :enum)
+
+      return {
+        :type => extract(doc_map, :class, :type),
+        :default => extract(doc_map, :class, :default),
+      }
+    end
+
     # Combines :doc-s of most tags
     # Ignores tags that have doc comment themselves and subproperty tags
     def detect_doc(docs)

data/lib/jsduck/doc_formatter.rb

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 require 'rubygems'
-require 'rdiscount'
 require 'strscan'
+require 'jsduck/markdown'
 require 'jsduck/logger'
 require 'jsduck/inline_img'
 require 'jsduck/inline_video'
@@ -133,12 +133,12 @@ module JsDuck
         text = $2
         if target =~ /^(.*)#(static-)?(?:(cfg|property|method|event|css_var|css_mixin)-)?(.*)$/
           cls = $1.empty? ? @class_context : $1
-          static = !!$2
+          static = $2 ? true : nil
           type = $3 ? $3.intern : nil
           member = $4
         else
           cls = target
-          static = false
+          static = nil
           type = false
           member = false
         end
@@ -257,7 +257,7 @@ module JsDuck
     end
 
     # applies the link template
-    def link(cls, member, anchor_text, type=nil, static=false)
+    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
@@ -281,7 +281,7 @@ module JsDuck
       end
     end
 
-    def get_matching_member(cls, member, type=nil, static=false)
+    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] }
@@ -291,7 +291,7 @@ module JsDuck
       end
     end
 
-    def get_members(cls, member, type=nil, static=false)
+    def get_members(cls, member, type=nil, static=nil)
       @relations[cls] ? @relations[cls].get_members(member, type, static) : []
     end
 
@@ -310,7 +310,7 @@ module JsDuck
       # code-blocks beginning with empty line.
       input.gsub!(/<pre>(<code>)?\n?/, "<pre>\\1")
 
-      replace(RDiscount.new(input).to_html)
+      replace(JsDuck::Markdown.to_html(input))
     end
 
     # Shortens text

data/lib/jsduck/doc_parser.rb

@@ -130,6 +130,8 @@ module JsDuck
           at_var
         elsif look(/@throws\b/)
           at_throws
+        elsif look(/@enum\b/)
+          at_enum
         elsif look(/@inheritable\b/)
           boolean_at_tag(/@inheritable/, :inheritable)
         elsif look(/@accessor\b/)
@@ -282,6 +284,16 @@ module JsDuck
       skip_white
     end
 
+    # matches @enum {type} name ...
+    def at_enum
+      match(/@enum/)
+      add_tag(:class)
+      @current_tag[:enum] = true
+      maybe_type
+      maybe_name_with_default
+      skip_white
+    end
+
     # matches @type {type}  or  @type type
     #
     # The presence of @type implies that we are dealing with property.

data/lib/jsduck/enum.rb

@@ -0,0 +1,73 @@
+module JsDuck
+
+  class Enum
+    def initialize(classes)
+      @classes = classes
+    end
+
+    # Applies additional processing to all enum-classes.
+    def process_all!
+      @classes.each_value do |cls|
+        if cls[:enum]
+          process(cls)
+        end
+      end
+    end
+
+    private
+
+    # processes single class
+    def process(cls)
+      expand_default(cls)
+      strip_inheritdoc(cls)
+      cls[:enum][:type] = infer_type(cls) unless cls[:enum][:type]
+    end
+
+    # Given an enum class, returns the type infered from its values.
+    def infer_type(cls)
+      if cls[:members][:property].length > 0
+        types = cls[:members][:property].map {|p| p[:type] }
+        types.sort.uniq.join("/")
+      else
+        "Object"
+      end
+    end
+
+    # Expands default value like widget.* into list of properties
+    def expand_default(cls)
+      if cls[:enum][:default] =~ /\A(.*)\.\*\Z/
+        each_alias($1) do |name, owner|
+          cls[:members][:property] << {
+            :tagname => :property,
+            :id => 'property-' + name,
+            :name => name,
+            :default => "'" + name + "'",
+            :type => "String",
+            :meta => {:private => owner[:private]},
+            :private => owner[:private],
+            :files => cls[:files],
+            :owner => cls[:name],
+            :doc => "Alias for {@link #{owner[:name]}}.",
+          }
+        end
+      end
+    end
+
+    def each_alias(prefix)
+      @classes.each_value do |cls|
+        if cls[:aliases] && cls[:aliases][prefix]
+          cls[:aliases][prefix].each {|name| yield(name, cls) }
+        end
+      end
+    end
+
+    # Remove the auto-inserted inheritdoc tag so the auto-detected enum
+    # values default to being public.
+    def strip_inheritdoc(cls)
+      cls[:members][:property].each do |p|
+        p[:inheritdoc] = nil if p[:autodetected]
+      end
+    end
+  end
+
+end

data/lib/jsduck/guide_writer.rb

@@ -10,7 +10,6 @@ module JsDuck
     def initialize(exporter_class, guides, opts)
       @guides = guides
       @exporter = exporter_class.new(guides, opts)
-      @parallel = ParallelWrap.new(:in_processes => opts.processes)
     end
 
     # Writes guide data into given directory or STDOUT when dir == :stdout.
@@ -24,13 +23,13 @@ module JsDuck
     private
 
     def write_stdout
-      json = @parallel.map(all_guides) {|guide| @exporter.export_guide(guide) }.compact
+      json = ParallelWrap.map(all_guides) {|guide| @exporter.export_guide(guide) }.compact
       Stdout.instance.add(json)
     end
 
     def write_dir(dir, extension)
       FileUtils.mkdir(dir) unless File.exists?(dir)
-      @parallel.each(all_guides) do |guide|
+      ParallelWrap.each(all_guides) do |guide|
         filename = dir + "/" + guide["name"] + extension
         Logger.instance.log("Writing guide", filename)
         json = @exporter.export_guide(guide)

data/lib/jsduck/guides.rb

@@ -36,15 +36,13 @@ module JsDuck
     end
 
     # Modified each_item that also loads HTML for each guide
-    def each_item(&block)
-      unless @loaded
-        super do |guide|
-          guide[:html] = load_guide(guide)
-        end
-        @loaded = true
+    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]
       end
-
-      super(&block)
     end
 
     # Modified to_array that excludes the :html from guide nodes
@@ -60,12 +58,13 @@ module JsDuck
     def load_guide(guide)
       in_dir = @path + "/guides/" + guide["name"]
 
-      begin
-        return Logger.instance.warn(:guide, "Guide #{in_dir} not found") unless File.exists?(in_dir)
+      return Logger.instance.warn(:guide, "Guide #{in_dir} not found") unless File.exists?(in_dir)
 
-        guide_file = in_dir + "/README.md"
-        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/importer.rb

@@ -0,0 +1,102 @@
+require 'jsduck/json_duck'
+require 'jsduck/null_object'
+require 'jsduck/logger'
+require 'jsduck/parallel_wrap'
+
+module JsDuck
+
+  # Reads in JSDuck exports of different versions of docs.
+  module Importer
+    module_function
+
+    # Loads in exported docs and generates @since and @new tags based on that data.
+    def import(imports, relations)
+      if imports.length > 0
+        generate_since_tags(read_all(imports), relations)
+      end
+    end
+
+    # Reads in data for all versions, returning array of
+    # version/class-data pairs.  We don't use a hash to preserve the
+    # order of versions (from oldest to newest).
+    def read_all(imports)
+      imports.map do |ver|
+        {
+          :version => ver[:version],
+          :classes => ver[:path] ? read(ver) : current_version,
+        }
+      end
+    end
+
+    def current_version
+      NullObject.new(:[] => NullObject.new(:[] => true))
+    end
+
+    # Reads in data from all .json files in directory
+    def read(ver)
+      # Map list of files into pairs of (classname, members-hash)
+      pairs = ParallelWrap.map(Dir[ver[:path] + "/*.json"]) do |filename|
+        JsDuck::Logger.instance.log("Importing #{ver[:version]}", filename)
+        json = JsonDuck.read(filename)
+        [json["name"],  members_id_index(json)]
+      end
+
+      # Turn key-value pairs array into hash
+      return Hash[ pairs ]
+    end
+
+    # creates index of all class members
+    def members_id_index(json)
+      index = {}
+      ["members", "statics"].each do |group_name|
+        json[group_name].each_pair do |tagname, members|
+          members.each do |m|
+            index[m["id"]] = true
+          end
+        end
+      end
+      index
+    end
+
+    # Using the imported versions data, adds @since tags to all
+    # classes/members.
+    def generate_since_tags(versions, relations)
+      last_version = versions.last[:version]
+
+      relations.each do |cls|
+        v = cls[:meta][:since] || class_since(versions, cls)
+        cls[:meta][:since] = v
+        cls[:meta][:new] = true if v == last_version
+
+        cls.all_local_members.each do |m|
+          v = m[:meta][:since] || member_since(versions, cls, m)
+          m[:meta][:since] = v
+          m[:meta][:new] = true if v == last_version
+        end
+      end
+    end
+
+    def member_since(versions, 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
+
+    # Returns name of the version since which the class is available
+    def class_since(versions, 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
+
+  end
+
+end