jsduck 4.0.beta2 → 4.0.0

data/js-classes/String.js

@@ -949,7 +949,7 @@
  *
  * The following example displays the string "sencha":
  *
- *     var upperText="sencha";
+ *     var upperText="SENCHA";
  *     document.write(upperText.toLocaleLowerCase());
  *
  * @return {String} Returns value of the string in lowercase.

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.0.beta2'
-  s.date = '2012-08-01'
+  s.version = '4.0.0'
+  s.date = '2012-08-09'
   s.summary = "Simple JavaScript Duckumentation generator"
   s.description = "Documentation generator for Sencha JS frameworks"
   s.homepage = "https://github.com/senchalabs/jsduck"
@@ -16,15 +16,13 @@ Gem::Specification.new do |s|
   end
   # Add files not in git
   s.files += Dir['template-min/**/*']
-  # Add Esprima
-  s.files += Dir['esprima/esprima.js']
 
   s.executables = ["jsduck"]
 
   s.add_dependency 'rdiscount'
   s.add_dependency 'json'
   s.add_dependency 'parallel'
-  s.add_dependency 'execjs'
+  s.add_dependency 'therubyracer'
 
   s.add_development_dependency 'rspec'
   s.add_development_dependency 'rake'

data/lib/jsduck/aggregator.rb

@@ -2,6 +2,7 @@ require 'jsduck/class'
 require 'jsduck/accessors'
 require 'jsduck/logger'
 require 'jsduck/enum'
+require 'jsduck/override'
 
 module JsDuck
 
@@ -206,10 +207,7 @@ module JsDuck
     end
 
     # Appends Ext4 options parameter to each event parameter list.
-    # But only when we are dealing with Ext4 codebase.
     def append_ext4_event_options
-      return unless ext4?
-
       options = {
         :tagname => :param,
         :name => "eOpts",
@@ -234,6 +232,11 @@ module JsDuck
       Enum.new(@classes).process_all!
     end
 
+    # Processes all overrides
+    def process_overrides
+      Override.new(@classes, @documentation).process_all!
+    end
+
     # Are we dealing with ExtJS 4?
     # True if any of the classes is defined with Ext.define()
     def ext4?

data/lib/jsduck/app.rb

@@ -47,7 +47,7 @@ module JsDuck
       result = aggregate(parsed_files)
       @relations = filter_classes(result)
       InheritDoc.new(@relations).resolve_all
-      Importer.import(@opts.imports, @relations)
+      Importer.import(@opts.imports, @relations, @opts.new_since)
       Lint.new(@relations).run
 
       # Initialize guides, videos, examples, ...
@@ -109,7 +109,7 @@ module JsDuck
         begin
           SourceFile.new(JsDuck::IO.read(fname), fname, @opts)
         rescue
-          Logger.instance.fatal("Error while parsing #{fname}", $!)
+          Logger.instance.fatal_backtrace("Error while parsing #{fname}", $!)
           exit(1)
         end
       end
@@ -126,8 +126,11 @@ module JsDuck
       agr.create_global_class
       agr.remove_ignored_classes
       agr.create_accessors
-      agr.append_ext4_event_options
+      if @opts.ext4_events == true || (@opts.ext4_events == nil && agr.ext4?)
+        agr.append_ext4_event_options
+      end
       agr.process_enums
+      agr.process_overrides
       agr.result
     end
 
@@ -166,14 +169,15 @@ module JsDuck
       class_formatter.include_types = !@opts.export
       # Format all doc-objects in parallel
       formatted_classes = ParallelWrap.map(@relations.classes) do |cls|
-        Logger.instance.log("Markdown formatting #{cls[:name]}")
+        files = cls[:files].map {|f| f[:filename] }.join(" ")
+        Logger.instance.log("Markdown formatting #{cls[:name]}", files)
         begin
           {
             :doc => class_formatter.format(cls.internal_doc),
             :images => doc_formatter.images
           }
         rescue
-          Logger.instance.fatal("Error while formatting #{cls[:name]}", $!)
+          Logger.instance.fatal_backtrace("Error while formatting #{cls[:name]} #{files}", $!)
           exit(1)
         end
       end

data/lib/jsduck/ast.rb

@@ -230,7 +230,9 @@ module JsDuck
       each_pair_in_object_expression(ast["arguments"][1]) do |key, value, pair|
         case key
         when "extend"
-          cls[:extends] = make_extends(value)
+          cls[:extends] = make_string(value)
+        when "override"
+          cls[:override] = make_string(value)
         when "requires"
           cls[:requires] = make_string_list(value)
         when "uses"
@@ -288,7 +290,7 @@ module JsDuck
       end
     end
 
-    def make_extends(cfg_value)
+    def make_string(cfg_value)
       return nil unless cfg_value
 
       parent = to_value(cfg_value)

data/lib/jsduck/class.rb

@@ -147,8 +147,10 @@ module JsDuck
       # Singletons have no static members
       if @doc[:singleton] && context == :statics
         # Warn if singleton has static members
-        if @doc[context][type].length > 0
-          Logger.instance.warn(:sing_static, "Singleton class #{@doc[:name]} can't have static members, remove the @static tag.")
+        @doc[context][type].each do |m|
+          ctx = m[:files][0]
+          msg = "Singleton class #{@doc[:name]} can't have static members, remove the @static tag."
+          Logger.instance.warn(:sing_static, msg, ctx[:filename], ctx[:linenr])
         end
         return {}
       end
@@ -185,7 +187,8 @@ module JsDuck
             hash1.delete(name)
           else
             ctx = m[:files][0]
-            Logger.instance.warn(:hide, "@hide used but #{m[:tagname]} #{m[:name]} not found in parent class", ctx[:filename], ctx[:linenr])
+            msg = "@hide used but #{m[:tagname]} #{m[:name]} not found in parent class"
+            Logger.instance.warn(:hide, msg, ctx[:filename], ctx[:linenr])
           end
         else
           if hash1[name]
@@ -264,6 +267,11 @@ module JsDuck
       return ms
     end
 
+    # Call this when renaming or moving members inside class.
+    def reset_members_lookup!
+      @members_map = nil
+    end
+
     # Returns all members of class, including the inherited and mixed in ones
     def all_members
       all = []

data/lib/jsduck/css_parser.rb

@@ -27,14 +27,15 @@ module JsDuck
       @docs
     end
 
-    # <code-block> := <mixin-declaration> | <var-declaration> | <nop>
+    # <code-block> := <mixin-declaration> | <var-declaration> | <property>
     def code_block
       if look("@mixin")
         mixin_declaration
       elsif look(:var, ":")
         var_declaration
       else
-        {:tagname => :nop}
+        # Default to property like in JsParser.
+        {:tagname => :property}
       end
     end
 

data/lib/jsduck/doc_ast.rb

@@ -52,6 +52,7 @@ module JsDuck
         :requires => detect_list(:requires, doc_map),
         :uses => detect_list(:uses, doc_map),
         :enum => detect_enum(doc_map),
+        :override => extract(doc_map, :override, :class),
       }, doc_map)
     end
 

data/lib/jsduck/doc_formatter.rb

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 require 'rubygems'
 require 'strscan'
-require 'jsduck/markdown'
+require 'rdiscount'
 require 'jsduck/logger'
 require 'jsduck/inline_img'
 require 'jsduck/inline_video'
@@ -95,7 +95,7 @@ module JsDuck
           out += replace_link_tag(s.scan(@link_re))
         elsif substitute = @inline_img.replace(s)
           out += substitute
-        elsif substitute = @inline_video.replace(s)
+        elsif substitute = @inline_video.replace(s, @doc_context)
           out += substitute
         elsif s.check(/[{]/)
           # There might still be "{" that doesn't begin {@link} or {@img} - ignore it
@@ -310,7 +310,7 @@ module JsDuck
       # code-blocks beginning with empty line.
       input.gsub!(/<pre>(<code>)?\n?/, "<pre>\\1")
 
-      replace(JsDuck::Markdown.to_html(input))
+      replace(RDiscount.new(input).to_html)
     end
 
     # Shortens text

data/lib/jsduck/doc_parser.rb

@@ -132,6 +132,8 @@ module JsDuck
           at_throws
         elsif look(/@enum\b/)
           at_enum
+        elsif look(/@override\b/)
+          at_override
         elsif look(/@inheritable\b/)
           boolean_at_tag(/@inheritable/, :inheritable)
         elsif look(/@accessor\b/)
@@ -294,6 +296,14 @@ module JsDuck
       skip_white
     end
 
+    # matches @override name ...
+    def at_override
+      match(/@override/)
+      add_tag(:override)
+      maybe_ident_chain(:class)
+      skip_white
+    end
+
     # matches @type {type}  or  @type type
     #
     # The presence of @type implies that we are dealing with property.

data/lib/jsduck/esprima.rb

@@ -1,12 +1,10 @@
-require 'execjs'
+require 'v8'
 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).
+  # Runs Esprima.js through V8.
   #
   # Initialized as singleton to avoid loading the esprima.js more
   # than once - otherwise performace will severely suffer.
@@ -14,17 +12,17 @@ module JsDuck
     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)
+      @v8 = V8::Context.new
+      esprima = File.dirname(File.dirname(File.dirname(File.expand_path(__FILE__))))+"/esprima/esprima.js";
+      @v8.load(esprima)
     end
 
     # Parses JavaScript source code using Esprima.js
     #
     # Returns the resulting AST
     def parse(input)
-      json = @context.call("runEsprima", input)
+      @v8['js'] = input
+      json = @v8.eval("JSON.stringify(esprima.parse(js, {comment: true, range: true, raw: true}))")
       return JSON.parse(json, :max_nesting => false)
     end
 

data/lib/jsduck/examples.rb

@@ -20,7 +20,7 @@ module JsDuck
       @groups = JsonDuck.read(filename)
       @opts = opts
       fix_examples_data
-      build_map_by_name("Two examples have the same name")
+      build_map_by_name("Two examples have the same name", filename)
     end
 
     # Prefix all relative URL-s in examples list with path given in --examples-base-url

data/lib/jsduck/file_categories.rb

@@ -13,7 +13,7 @@ module JsDuck
 
       # Don't crash if old syntax is used.
       if @categories.is_a?(Hash) && @categories["categories"]
-        Logger.instance.warn(nil, 'Update categories file to contain just the array inside {"categories": [...]}')
+        Logger.instance.warn(nil, 'Update categories file to contain just the array inside {"categories": [...]}', @filename)
         @categories = @categories["categories"]
       end
 
@@ -36,7 +36,7 @@ module JsDuck
       re = Regexp.new("^" + name.split(/\*/, -1).map {|part| Regexp.escape(part) }.join('.*') + "$")
       classes = @relations.to_a.find_all {|cls| re =~ cls[:name] && !cls[:private] }.map {|cls| cls[:name] }.sort
       if classes.length == 0
-        Logger.instance.warn(:cat_no_match, "No class found matching a pattern '#{name}' in categories file.")
+        Logger.instance.warn(:cat_no_match, "No class found matching a pattern '#{name} in categories file'", @filename)
       end
       classes
     end
@@ -56,7 +56,7 @@ module JsDuck
       # Check that each existing non-private class is listed
       @relations.each do |cls|
         unless listed_classes[cls[:name]] || cls[:private]
-          Logger.instance.warn(:cat_class_missing, "Class '#{cls[:name]}' not found in categories file")
+          Logger.instance.warn(:cat_class_missing, "Class '#{cls[:name]}' not found in categories file", @filename)
         end
       end
     end

data/lib/jsduck/grouped_asset.rb

@@ -13,13 +13,13 @@ module JsDuck
     #
     # Prints warning when there is a duplicate item within a group.
     # The warning message should say something like "duplicate <asset type>"
-    def build_map_by_name(warning_msg)
+    def build_map_by_name(warning_msg, filename)
       @map_by_name = {}
       @groups.each do |group|
         group_map = {}
         group["items"].each do |item|
           if group_map[item["name"]]
-            Logger.instance.warn(:dup_asset, "#{warning_msg} '#{item['name']}'")
+            Logger.instance.warn(:dup_asset, "#{warning_msg} '#{item['name']}'", filename)
           end
           @map_by_name[item["name"]] = item
           group_map[item["name"]] = item

data/lib/jsduck/guides.rb

@@ -24,7 +24,7 @@ module JsDuck
     def initialize(filename, formatter, opts)
       @path = File.dirname(filename)
       @groups = JsonDuck.read(filename)
-      build_map_by_name("Two guides have the same name")
+      build_map_by_name("Two guides have the same name", filename)
       @formatter = formatter
       @opts = opts
     end
@@ -58,11 +58,11 @@ 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)
+      return Logger.instance.warn(:guide, "Guide not found", in_dir) 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)
+      return Logger.instance.warn(:guide, "Guide not found", guide_file) unless File.exists?(guide_file)
 
       begin
         @formatter.doc_context = {:filename => guide_file, :linenr => 0}
@@ -71,7 +71,7 @@ module JsDuck
 
         return add_toc(guide, @formatter.format(JsDuck::IO.read(guide_file)))
       rescue
-        Logger.instance.fatal("Error while reading/formatting guide #{in_dir}", $!)
+        Logger.instance.fatal_backtrace("Error while reading/formatting guide #{in_dir}", $!)
         exit(1)
       end
     end

data/lib/jsduck/importer.rb

@@ -10,9 +10,9 @@ module JsDuck
     module_function
 
     # Loads in exported docs and generates @since and @new tags based on that data.
-    def import(imports, relations)
+    def import(imports, relations, new_since=nil)
       if imports.length > 0
-        generate_since_tags(read_all(imports), relations)
+        generate_since_tags(read_all(imports), relations, new_since)
       end
     end
 
@@ -60,22 +60,41 @@ module JsDuck
 
     # Using the imported versions data, adds @since tags to all
     # classes/members.
-    def generate_since_tags(versions, relations)
-      last_version = versions.last[:version]
+    def generate_since_tags(versions, relations, new_since=nil)
+      new_versions = build_new_versions_map(versions, new_since)
 
       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[:meta][:new] = true if new_versions[v]
 
         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
+          m[:meta][:new] = true if new_versions[v]
         end
       end
     end
 
+    # Generates a lookup table of versions that we are going to label
+    # with @new tags.  By default we use the latest version, otherwise
+    # use all versions since the latest.
+    def build_new_versions_map(versions, new_since=nil)
+      new_versions = {}
+
+      if new_since
+        versions.map {|v| v[:version] }.each do |v|
+          if v == new_since || !new_versions.empty?
+            new_versions[v] = true
+          end
+        end
+      else
+        new_versions[versions.last[:version]] = true
+      end
+
+      new_versions
+    end
+
     def member_since(versions, cls, m)
       versions.each do |ver|
         c = ver[:classes][cls[:name]]

data/lib/jsduck/inherit_doc.rb

@@ -55,6 +55,9 @@ module JsDuck
         cls[:members][:property].delete(m)
         cls[:members][:cfg] << m
       end
+      # The members lookup table inside class is no more valid, so
+      # reset it.
+      cls.reset_members_lookup!
     end
 
     # For auto-detected members/classes (which have @private == :inherit)

data/lib/jsduck/inline_video.rb

@@ -28,18 +28,18 @@ module JsDuck
     # Looks for inline tag at the current scan pointer position, when
     # found, moves scan pointer forward and performs the apporpriate
     # replacement.
-    def replace(input)
+    def replace(input, doc_context)
       if input.check(@re)
-        input.scan(@re).sub(@re) { apply_tpl($1, $2, $3) }
+        input.scan(@re).sub(@re) { apply_tpl($1, $2, $3, doc_context) }
       else
         false
       end
     end
 
     # applies the video template of the specified type
-    def apply_tpl(type, url, alt_text)
+    def apply_tpl(type, url, alt_text, ctx)
       unless @templates.has_key?(type)
-        Logger.instance.warn(nil, "Unknown video type #{type}")
+        Logger.instance.warn(nil, "Unknown video type #{type}", ctx[:filename], ctx[:linenr])
       end
 
       @templates[type].gsub(/(%\w)/) do