jsduck 4.4.1 → 4.5.0

data/.travis.yml

@@ -6,6 +6,6 @@ install:
   - gem install rdiscount
   - gem install json
   - gem install parallel
-  - gem install therubyracer
+  - gem install therubyracer -v 0.10.1
   - gem install rspec
   - gem install rake

data/README.md

@@ -141,6 +141,7 @@ Who's using JSDuck?
 - Appcelerator [Titanium SDK](http://docs.appcelerator.com/titanium/2.0/index.html)
 - AT&T [API Platform SDK for HTML5](https://code-api-att.com/SenchaSdk20Drop23Docs/)
 - Bryntum [Siesta unit testing framework](http://www.bryntum.com/products/siesta/docs/)
+- [CKEditor](http://docs.ckeditor.com)
 - [GeoExt 2](https://github.com/geoext/geoext2)
 - Rally Software [Rally App SDK](https://rally1.rallydev.com/apps/2.0p/doc/)
 - [Sencha](http://docs.sencha.com) - obviously :)

data/Rakefile

@@ -104,7 +104,7 @@ def compress
   dir = "template-min"
 
   # Create JSB3 file for Docs app
-  system("sencha", "create", "jsb", "-a", "http://localhost/docs/", "-p", "#{dir}/app.jsb3")
+  system("sencha", "create", "jsb", "-a", "http://localhost/~renesaarsoo/docs/", "-p", "#{dir}/app.jsb3")
   # Concatenate files listed in JSB3 file
   system("sencha", "build", "-p", "#{dir}/app.jsb3", "-d", dir)
 

data/jsduck.gemspec

@@ -2,8 +2,8 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = ">= 1.3.5"
 
   s.name = 'jsduck'
-  s.version = '4.4.1'
-  s.date = '2012-11-20'
+  s.version = '4.5.0'
+  s.date = '2012-12-06'
   s.summary = "Simple JavaScript Duckumentation generator"
   s.description = "Documentation generator for Sencha JS frameworks"
   s.homepage = "https://github.com/senchalabs/jsduck"
@@ -22,7 +22,7 @@ Gem::Specification.new do |s|
   s.add_dependency 'rdiscount'
   s.add_dependency 'json'
   s.add_dependency 'parallel'
-  s.add_dependency 'therubyracer'
+  s.add_dependency 'therubyracer', '= 0.10.1'
 
   s.add_development_dependency 'rspec'
   s.add_development_dependency 'rake'

data/lib/jsduck/ast.rb

@@ -1,6 +1,7 @@
 require "jsduck/serializer"
 require "jsduck/evaluator"
 require "jsduck/function_ast"
+require "jsduck/ext_patterns"
 
 module JsDuck
 
@@ -10,21 +11,10 @@ module JsDuck
     def initialize(docs = [], options = {})
       @serializer = JsDuck::Serializer.new
       @evaluator = JsDuck::Evaluator.new
-      @ext_define_patterns = build_ext_define_patterns(options[:ext_namespaces] || ["Ext"])
+      @ext_patterns = JsDuck::ExtPatterns.new(options[:ext_namespaces] || ["Ext"])
       @docs = docs
     end
 
-    # Given Array of alternate Ext namespaces builds list of patterns
-    # for detecting Ext.define:
-    #
-    # ["Ext","Foo"] --> ["Ext.define", "Ext.ClassManager.create", "Foo.define", "Foo.ClassManager.create"]
-    #
-    def build_ext_define_patterns(namespaces)
-      namespaces.map do |ns|
-        [ns + ".define", ns + ".ClassManager.create"]
-      end.flatten
-    end
-
     # Performs the detection of code in all docsets.
     #
     # @returns the processed array of docsets. (But it does it
@@ -68,7 +58,11 @@ module JsDuck
       if exp && ext_define?(exp)
         make_class(to_value(exp["arguments"][0]), exp)
 
-      # foo = Ext.extend("Parent", {})
+      # Ext.override(Class, {})
+      elsif exp && ext_override?(exp)
+        make_class("", exp)
+
+      # foo = Ext.extend(Parent, {})
       elsif exp && assignment?(exp) && ext_extend?(exp["right"])
         make_class(to_s(exp["left"]), exp["right"])
 
@@ -76,7 +70,7 @@ module JsDuck
       elsif exp && assignment?(exp) && class_name?(to_s(exp["left"]))
         make_class(to_s(exp["left"]), exp["right"])
 
-      # var foo = Ext.extend("Parent", {})
+      # var foo = Ext.extend(Parent, {})
       elsif var && var["init"] && ext_extend?(var["init"])
         make_class(to_s(var["id"]), var["init"])
 
@@ -88,6 +82,10 @@ module JsDuck
       elsif function?(ast) && class_name?(to_s(ast["id"]))
         make_class(to_s(ast["id"]))
 
+      # { ... }
+      elsif object?(ast)
+        make_class("", ast)
+
       # function foo() {}
       elsif function?(ast)
         make_method(to_s(ast["id"]), ast)
@@ -108,6 +106,10 @@ module JsDuck
       elsif property?(ast) && function?(ast["value"])
         make_method(key_value(ast["key"]), ast["value"])
 
+      # this.fireEvent("foo", ...)
+      elsif exp && fire_event?(exp)
+        make_event(to_value(exp["arguments"][0]))
+
       # foo = ...
       elsif exp && assignment?(exp)
         make_property(to_s(exp["left"]), exp["right"])
@@ -152,11 +154,15 @@ module JsDuck
     end
 
     def ext_define?(ast)
-      call?(ast) && @ext_define_patterns.include?(to_s(ast["callee"]))
+      call?(ast) && ext_pattern?("Ext.define", ast["callee"])
     end
 
     def ext_extend?(ast)
-      call?(ast) && to_s(ast["callee"]) == "Ext.extend"
+      call?(ast) && ext_pattern?("Ext.extend", ast["callee"])
+    end
+
+    def ext_override?(ast)
+      call?(ast) && ext_pattern?("Ext.override", ast["callee"])
     end
 
     def function?(ast)
@@ -164,7 +170,15 @@ module JsDuck
     end
 
     def empty_fn?(ast)
-      ast["type"] == "MemberExpression" && to_s(ast) == "Ext.emptyFn"
+      ast["type"] == "MemberExpression" && ext_pattern?("Ext.emptyFn", ast)
+    end
+
+    def ext_pattern?(pattern, ast)
+      @ext_patterns.matches?(pattern, to_s(ast))
+    end
+
+    def fire_event?(ast)
+      call?(ast) && to_s(ast["callee"]) == "this.fireEvent"
     end
 
     def var?(ast)
@@ -183,6 +197,10 @@ module JsDuck
       ast["type"] == "Literal" && ast["value"].is_a?(String)
     end
 
+    def object?(ast)
+      ast["type"] == "ObjectExpression"
+    end
+
     # Class name begins with upcase char
     def class_name?(name)
       return name.split(/\./).last =~ /\A[A-Z]/
@@ -196,15 +214,13 @@ module JsDuck
 
       # apply information from Ext.extend, Ext.define, or {}
       if ast
-        if ext_extend?(ast)
-          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)
+        if ext_define?(ast)
           detect_ext_define(cls, ast)
-        elsif ast["type"] == "ObjectExpression"
+        elsif ext_extend?(ast)
+          detect_ext_something(:extends, cls, ast)
+        elsif ext_override?(ast)
+          detect_ext_something(:override, cls, ast)
+        elsif object?(ast)
           detect_class_members_from_object(cls, ast)
         elsif ast["type"] == "ArrayExpression"
           detect_class_members_from_array(cls, ast)
@@ -214,6 +230,16 @@ module JsDuck
       return cls
     end
 
+    # Detection of Ext.extend() or Ext.override().
+    # The type parameter must be correspondingly either :extend or :override.
+    def detect_ext_something(type, cls, ast)
+      args = ast["arguments"]
+      cls[type] = to_s(args[0])
+      if args.length == 2 && object?(args[1])
+        detect_class_members_from_object(cls, args[1])
+      end
+    end
+
     # Inspects Ext.define() and copies detected properties over to the
     # given cls Hash
     def detect_ext_define(cls, ast)
@@ -419,6 +445,13 @@ module JsDuck
       end
     end
 
+    def make_event(name)
+      return {
+        :tagname => :event,
+        :name => name,
+      }
+    end
+
     def make_property(name=nil, ast=nil, tagname=:property)
       return {
         :tagname => tagname,
@@ -461,7 +494,7 @@ module JsDuck
     # are turned into strings, but values are left as is for further
     # processing.
     def each_pair_in_object_expression(ast)
-      return unless ast && ast["type"] == "ObjectExpression"
+      return unless ast && object?(ast)
 
       ast["properties"].each do |p|
         yield(key_value(p["key"]), p["value"], p)

data/lib/jsduck/doc_parser.rb

@@ -1,5 +1,6 @@
 require 'strscan'
 require 'jsduck/meta_tag_registry'
+require 'jsduck/logger'
 
 module JsDuck
 
@@ -28,7 +29,9 @@ module JsDuck
       @meta_tags = MetaTagRegistry.instance
     end
 
-    def parse(input)
+    def parse(input, filename="", linenr=0)
+      @filename = filename
+      @linenr = linenr
       @tags = []
       @input = StringScanner.new(purify(input))
       parse_loop
@@ -77,6 +80,11 @@ module JsDuck
       @tags << @current_tag = {:tagname => tag, :doc => ""}
     end
 
+    def remove_last_tag
+      @tags.pop
+      @current_tag = @tags.last
+    end
+
     def parse_loop
       add_tag(:default)
       while !@input.eos? do
@@ -141,19 +149,56 @@ module JsDuck
         elsif look(/@evented\b/)
           boolean_at_tag(/@evented/, :evented)
         elsif look(/@/)
-          match(/@/)
-          tag = @meta_tags[look(/\w+/)]
-          if tag
-            meta_at_tag(tag)
-          else
-            @current_tag[:doc] += "@"
-          end
+          other_at_tag
         elsif look(/[^@]/)
-          @current_tag[:doc] += match(/[^@]+/)
+          skip_to_next_at_tag
         end
       end
     end
 
+    # Skips until the beginning of next @tag.
+    #
+    # There must be space before the next @tag - this ensures that we
+    # don't detect tags inside "foo@example.com" or "{@link}".
+    #
+    # Also check that the @tag is not part of an indented code block -
+    # in which case we also ignore the tag.
+    def skip_to_next_at_tag
+      @current_tag[:doc] += match(/[^@]+/)
+
+      while look(/@/) && (!prev_char_is_whitespace? || indented_as_code?)
+        @current_tag[:doc] += match(/@+[^@]+/)
+      end
+    end
+
+    def prev_char_is_whitespace?
+      @current_tag[:doc][-1,1] =~ /\s/
+    end
+
+    def indented_as_code?
+      @current_tag[:doc] =~ /^ {4,}[^\n]*\Z/
+    end
+
+    # Processes anything else beginning with @-sign.
+    #
+    # - When @ is not followed by any word chards, do nothing.
+    # - When it's one of the meta-tags, process it as such.
+    # - When it's something else, print a warning.
+    #
+    def other_at_tag
+      match(/@/)
+
+      name = look(/\w+/)
+      tag = @meta_tags[name]
+
+      if tag
+        meta_at_tag(tag)
+      elsif name
+        Logger.warn(:tag, "Unsupported tag: @#{name}", @filename, @linenr)
+        @current_tag[:doc] += "@"
+      end
+    end
+
     # Matches the given meta-tag
     def meta_at_tag(tag)
       prev_tag = @current_tag
@@ -302,6 +347,14 @@ module JsDuck
       add_tag(:override)
       maybe_ident_chain(:class)
       skip_white
+
+      # When @override not followed by class name, ignore the tag.
+      # That's because the current ext codebase has some methods
+      # tagged with @override to denote they override something.
+      # But that's not what @override is meant for in JSDuck.
+      unless @current_tag[:class]
+        remove_last_tag
+      end
     end
 
     # matches @type {type}  or  @type type

data/lib/jsduck/doc_type.rb

@@ -12,7 +12,7 @@ module JsDuck
     def detect(docs, code)
       doc_map = build_doc_map(docs)
 
-      if doc_map[:class]
+      if doc_map[:class] || doc_map[:override]
         :class
       elsif doc_map[:event]
         :event
@@ -57,4 +57,3 @@ module JsDuck
   end
 
 end
-

data/lib/jsduck/ext_patterns.rb

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

@@ -0,0 +1,30 @@
+module JsDuck
+
+  # Handles patterns of external classes.
+  #
+  # A pattern can be a simple classname or a one with a wildcard "*".
+  class ExternalClasses
+
+    def initialize(classnames = [])
+      @class_names = {}
+      @patterns = []
+      classnames.each do |name|
+        if name =~ /\*/
+          @patterns << make_pattern(name)
+        else
+          @class_names[name] = true
+        end
+      end
+    end
+
+    # True if the classname matches an external class pattern.
+    def is?(classname)
+      @class_names[classname] || @patterns.any? {|p| classname =~ p }
+    end
+
+    def make_pattern(pattern)
+      Regexp.new("^" + pattern.split(/\*/, -1).map {|s| Regexp.escape(s) }.join(".*") + "$")
+    end
+  end
+
+end

data/lib/jsduck/js_parser.rb

@@ -138,17 +138,17 @@ module JsDuck
 
     # True if range A is less than range B
     def less(a, b)
-      return a[1] < b[0]
+      return a[1] <= b[0]
     end
 
     # True if range A is greater than range B
     def greater(a, b)
-      return a[0] > b[1]
+      return a[0] >= b[1]
     end
 
     # True if range A is within range B
     def within(a, b)
-      return b[0] < a[0] && a[1] < b[1]
+      return b[0] <= a[0] && a[1] <= b[1]
     end