jsduck 4.10.4 → 5.0.0.beta01

data/lib/jsduck/doc_type.rb

@@ -1,59 +0,0 @@
-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] || doc_map[:override]
-        :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
-      elsif doc_map[:param] || doc_map[:return]
-        :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/enum.rb

@@ -1,73 +0,0 @@
-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].length > 0
-        types = cls[:members].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] << {
-            :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].each do |p|
-        p[:inheritdoc] = nil if p[:autodetected]
-      end
-    end
-  end
-
-end

data/lib/jsduck/esprima.rb

@@ -1,51 +0,0 @@
-require 'execjs'
-require 'jsduck/util/json'
-require 'jsduck/util/singleton'
-
-module JsDuck
-
-  # Runs Esprima.js through JavaScript runtime selected by ExecJS.
-  # Normally this will be V8 engine within therubyracer gem, but when
-  # JSDuck is installed through some other means than rubygems, then
-  # one could use any of the runtimes supported by ExecJS.  (NodeJS
-  # for example.)
-  #
-  # Initialized as singleton to avoid loading the esprima.js more
-  # than once - otherwise performace will severely suffer.
-  class Esprima
-    include Util::Singleton
-
-    def initialize
-      esprima_path = File.dirname(File.expand_path(__FILE__)) + "/esprima/esprima.js"
-      esprima = IO.read(esprima_path)
-
-      # Esprima attempts to assign to window.esprima, but our v8
-      # engine has no global window variable defined.  So define our
-      # own and then grab esprima out from it again.
-      source = <<-EOJS
-        if (typeof window === "undefined") {
-            var window = {};
-        }
-
-        #{esprima}
-
-        var esprima = window.esprima;
-
-        function runEsprima(js) {
-          return JSON.stringify(esprima.parse(js, {comment: true, range: true, raw: true}));
-        }
-      EOJS
-
-      @context = ExecJS.compile(source)
-    end
-
-    # Parses JavaScript source code using Esprima.js
-    #
-    # Returns the resulting AST
-    def parse(input)
-      json = @context.call("runEsprima", input)
-      return Util::Json.parse(json, :max_nesting => false)
-    end
-
-  end
-end

data/lib/jsduck/evaluator.rb

@@ -1,69 +0,0 @@
-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/ext_patterns.rb

@@ -1,58 +0,0 @@
-module JsDuck
-
-  # Identifies Ext JS builtins like Ext.define and Ext.extend, taking
-  # also into account the possibility of aliasing the Ext namespace.
-  #
-  # For example when the following command line option is used:
-  #
-  #     --ext-namespaces=Ext,MyApp
-  #
-  # we need to identify both Ext.define and MyApp.define, but
-  # Ext.define is additionally aliased withing ExtJS as
-  # Ext.ClassManager.create, so we also need to recognize
-  # Ext.ClassManager.create and MyApp.ClassManager.create.
-  #
-  # The matches? method will take care of identifying all these four
-  # cases:
-  #
-  #     ps = ExtPatterns.new(["Ext", "MyApp"])
-  #     matches?("Ext.define", "MyApp.define") --> true
-  #
-  class ExtPatterns
-    def initialize(namespaces)
-      @patterns = {
-        "Ext.define" => build_patterns(namespaces, [".define", ".ClassManager.create"]),
-        "Ext.extend" => build_patterns(namespaces, [".extend"]),
-        "Ext.override" => build_patterns(namespaces, [".override"]),
-        "Ext.emptyFn" => build_patterns(namespaces, [".emptyFn"]),
-      }
-    end
-
-    # True when string matches the given pattern type.
-    #
-    # Pattern type is one of: "Ext.define", "Ext.extend",
-    # "Ext.override", "Ext.emptyFn"
-    def matches?(pattern, string)
-      @patterns[pattern].include?(string)
-    end
-
-    private
-
-    # Given Array of alternate Ext namespaces builds list of patterns
-    # for detecting Ext.define or some other construct:
-    #
-    # build_patterns(["Ext", "Foo"], [".define"]) --> ["Ext.define", "Foo.define"]
-    #
-    def build_patterns(namespaces, suffixes)
-      patterns = []
-      namespaces.each do |ns|
-        suffixes.each do |suffix|
-          patterns << ns + suffix
-        end
-      end
-      patterns
-    end
-
-  end
-
-end

data/lib/jsduck/file_categories.rb

@@ -1,76 +0,0 @@
-require 'jsduck/logger'
-require 'jsduck/util/json'
-
-module JsDuck
-
-  # Reads categories info from config file
-  class FileCategories
-    def initialize(filename, relations)
-      @filename = filename
-      @relations = relations
-    end
-
-    # Parses categories in JSON file
-    def generate
-      @categories = Util::Json.read(@filename)
-
-      # Don't crash if old syntax is used.
-      if @categories.is_a?(Hash) && @categories["categories"]
-        Logger.warn(nil, 'Update categories file to contain just the array inside {"categories": [...]}', @filename)
-        @categories = @categories["categories"]
-      end
-
-      # Perform expansion on all class names containing * wildcard
-      @categories.each do |cat|
-        cat["groups"].each do |group|
-          group["classes"] = group["classes"].map do |name|
-            expand(name)
-          end.flatten
-        end
-      end
-
-      validate
-
-      @categories
-    end
-
-    # Expands class name like 'Foo.*' into multiple class names.
-    def expand(name)
-      re = Regexp.new("^" + name.split(/\*/, -1).map {|part| Regexp.escape(part) }.join('.*') + "$")
-
-      classes = @relations.to_a.find_all do |cls|
-        re =~ cls[:name] && !cls[:private] && !deprecated?(cls)
-      end.map {|cls| cls[:name] }.sort
-
-      if classes.length == 0
-        Logger.warn(:cat_no_match, "No class found matching a pattern '#{name}' in categories file", @filename)
-      end
-      classes
-    end
-
-    # Prints warnings for missing classes in categories file
-    def validate
-      # Build a map of all classes listed in categories
-      listed_classes = {}
-      @categories.each do |cat|
-        cat["groups"].each do |group|
-          group["classes"].each do |cls_name|
-            listed_classes[cls_name] = true
-          end
-        end
-      end
-
-      # Check that each existing non-private & non-deprecated class is listed
-      @relations.each do |cls|
-        unless listed_classes[cls[:name]] || cls[:private] || deprecated?(cls)
-          Logger.warn(:cat_class_missing, "Class '#{cls[:name]}' not found in categories file", @filename)
-        end
-      end
-    end
-
-    def deprecated?(cls)
-      cls[:meta] && cls[:meta][:deprecated]
-    end
-  end
-
-end

data/lib/jsduck/function_ast.rb

@@ -1,206 +0,0 @@
-require "jsduck/util/singleton"
-require "jsduck/serializer"
-require "jsduck/evaluator"
-
-module JsDuck
-
-  # Analyzes the AST of a FunctionDeclaration or FunctionExpression.
-  class FunctionAst
-    include Util::Singleton
-
-    # Detects possible return types of the given function.
-    #
-    # For now there are three possible detected return values:
-    #
-    # * :this - the code contins 'return this;'
-    #
-    # * "undefined" - the code finishes by returning undefined or
-    #   without explicitly returning anything
-    #
-    # * :other - some other value is returned.
-    #
-    def return_types(ast)
-      h = return_types_hash(ast["body"]["body"])
-
-      # Replace the special :void value that signifies possibility of
-      # exiting without explicitly returning anything
-      if h[:void]
-        h["undefined"] = true
-        h.delete(:void)
-      end
-
-      h.keys
-    end
-
-    private
-
-    def return_types_hash(body)
-      rvalues = {}
-      body.each do |ast|
-        if return?(ast)
-          type = value_type(ast["argument"])
-          rvalues[type] = true
-          return rvalues
-        elsif possibly_blocking?(ast)
-          extract_bodies(ast).each do |b|
-            rvalues.merge!(return_types_hash(b))
-          end
-          if !rvalues[:void]
-            return rvalues
-          else
-            rvalues.delete(:void)
-          end
-        elsif control_flow?(ast)
-          extract_bodies(ast).each do |b|
-            rvalues.merge!(return_types_hash(b))
-          end
-          rvalues.delete(:void)
-        end
-      end
-
-      rvalues[:void] = true
-      return rvalues
-    end
-
-    def return?(ast)
-      ast["type"] == "ReturnStatement"
-    end
-
-    def value_type(ast)
-      if !ast
-        :void
-      elsif undefined?(ast) || void?(ast)
-        "undefined"
-      elsif this?(ast)
-        :this
-      elsif boolean?(ast)
-        "Boolean"
-      elsif string?(ast)
-        "String"
-      elsif regexp?(ast)
-        "RegExp"
-      else
-        :other
-      end
-    end
-
-    def undefined?(ast)
-      ast["type"] == "Identifier" && ast["name"] == "undefined"
-    end
-
-    def void?(ast)
-      ast["type"] == "UnaryExpression" && ast["operator"] == "void"
-    end
-
-    def this?(ast)
-      ast["type"] == "ThisExpression"
-    end
-
-    def boolean?(ast)
-      if boolean_literal?(ast)
-        true
-      elsif ast["type"] == "UnaryExpression" || ast["type"] == "BinaryExpression"
-        !!BOOLEAN_RETURNING_OPERATORS[ast["operator"]]
-      elsif ast["type"] == "LogicalExpression"
-        boolean?(ast["left"]) && boolean?(ast["right"])
-      elsif ast["type"] == "ConditionalExpression"
-        boolean?(ast["consequent"]) && boolean?(ast["alternate"])
-      elsif ast["type"] == "AssignmentExpression" && ast["operator"] == "="
-        boolean?(ast["right"])
-      else
-        false
-      end
-    end
-
-    def boolean_literal?(ast)
-      ast["type"] == "Literal" && (ast["value"] == true || ast["value"] == false)
-    end
-
-    def string?(ast)
-      if string_literal?(ast)
-        true
-      elsif ast["type"] == "BinaryExpression" && ast["operator"] == "+"
-        string?(ast["left"]) || string?(ast["right"])
-      elsif ast["type"] == "UnaryExpression" && ast["operator"] == "typeof"
-        true
-      else
-        false
-      end
-    end
-
-    def string_literal?(ast)
-      ast["type"] == "Literal" && ast["value"].is_a?(String)
-    end
-
-    def regexp?(ast)
-      ast["type"] == "Literal" && ast["raw"] =~ /^\//
-    end
-
-    def control_flow?(ast)
-      CONTROL_FLOW[ast["type"]]
-    end
-
-    def extract_bodies(ast)
-      body = []
-      CONTROL_FLOW[ast["type"]].each do |name|
-        statements = ast[name]
-        if statements.is_a?(Hash)
-          body << [statements]
-        else
-          body << Array(statements)
-        end
-      end
-      body
-    end
-
-    # True if the node is a control structure which will block further
-    # program flow when all its branches finish with a return
-    # statement.
-    def possibly_blocking?(ast)
-      if POSSIBLY_BLOCKING[ast["type"]]
-        CONTROL_FLOW[ast["type"]].all? {|key| ast[key] }
-      else
-        false
-      end
-    end
-
-    BOOLEAN_RETURNING_OPERATORS = {
-      "!" => true,
-      ">" => true,
-      ">=" => true,
-      "<" => true,
-      "<=" => true,
-      "==" => true,
-      "!=" => true,
-      "===" => true,
-      "!==" => true,
-      "in" => true,
-      "instanceof" => true,
-      "delete" => true,
-    }
-
-    POSSIBLY_BLOCKING = {
-      "IfStatement" => true,
-      "DoWhileStatement" => true,
-      "WithStatement" => true,
-      "LabeledStatement" => true,
-      "BlockStatement" => true,
-    }
-
-    CONTROL_FLOW = {
-      "IfStatement" => ["consequent", "alternate"],
-      "SwitchStatement" => ["cases"],
-      "SwitchCase" => ["consequent"],
-      "ForStatement" => ["body"],
-      "ForInStatement" => ["body"],
-      "WhileStatement" => ["body"],
-      "DoWhileStatement" => ["body"],
-      "TryStatement" => ["block", "handlers", "finalizer"],
-      "CatchClause" => ["body"],
-      "WithStatement" => ["body"],
-      "LabeledStatement" => ["body"],
-      "BlockStatement" => ["body"],
-    }
-  end
-
-end