jsduck 5.0.0.beta2 → 5.0.0.beta3

data/Rakefile

@@ -159,6 +159,11 @@ class JsDuckRunner
     add_options("--comments-domain", db_name+"/"+version)
   end
 
+  def add_search(product, version)
+    add_options("--search-url", "http://support-test.sencha.com:8080/docsearch/search")
+    add_options("--search-domain", product+"/"+version)
+  end
+
   def add_ext4
     @options += [
       "--title", "Sencha Docs - Ext JS 4.0",
@@ -263,6 +268,7 @@ task :sdk => :sass do
   )
   runner.add_debug
   runner.add_comments('ext-js', '4')
+  runner.add_search('Ext JS', '4.2.0')
   runner.run
 
   system("ln -s #{EXT_BUILD} #{OUT_DIR}/extjs-build")
@@ -275,10 +281,14 @@ task :touch2 => :sass do
     "--output", OUT_DIR,
     "--config", "#{SDK_DIR}/touch/docs/config.json",
     "--examples-base-url", "touch-build/examples/production/",
-    # "--import", "Touch 1.1:../docs.sencha.com/exports/touch-1.1",
-    # "--import", "Touch 2.0:../docs.sencha.com/exports/touch-2.0.1",
-    # "--import", "Touch 2.1.0:../docs.sencha.com/exports/touch-2.1.0",
-    # "--import", "Touch 2.1.1",
+    # "--import", "1.1.0:../docs.sencha.com/exports/touch-1.1.0",
+    # "--import", "1.1.1:../docs.sencha.com/exports/touch-1.1.1",
+    # "--import", "2.0.0:../docs.sencha.com/exports/touch-2.0.0",
+    # "--import", "2.0.1:../docs.sencha.com/exports/touch-2.0.1",
+    # "--import", "2.1.0:../docs.sencha.com/exports/touch-2.1.0",
+    # "--import", "2.1.1:../docs.sencha.com/exports/touch-2.1.1",
+    # "--import", "2.2.0:../docs.sencha.com/exports/touch-2.2.0",
+    # "--import", "2.2.1",
     "--seo"
   )
 

data/bin/jsduck

@@ -22,4 +22,6 @@ require 'jsduck/options'
 
 opts = JsDuck::Options.new
 opts.parse!(ARGV)
-JsDuck::App.new(opts).run
+exit_code = JsDuck::App.new(opts).run
+
+exit exit_code

data/jsduck.gemspec

@@ -2,7 +2,7 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = ">= 1.3.5"
 
   s.name = 'jsduck'
-  s.version = '5.0.0.beta2'
+  s.version = '5.0.0.beta3'
   s.date = Time.new.strftime('%Y-%m-%d')
   s.summary = "Simple JavaScript Duckumentation generator"
   s.description = "Documentation generator for Sencha JS frameworks"
@@ -23,7 +23,7 @@ Gem::Specification.new do |s|
   s.add_dependency 'json'
   s.add_dependency 'parallel'
   s.add_dependency 'execjs'
-  s.add_dependency 'therubyracer', '>= 0.10.0', '< 0.11.0'
+  s.add_dependency 'therubyracer', '>= 0.10.0'
   s.add_dependency 'dimensions'
 
   s.add_development_dependency 'rspec'

data/lib/jsduck/app.rb

@@ -4,6 +4,7 @@ require 'jsduck/assets'
 require 'jsduck/tag_registry'
 require 'jsduck/export_writer'
 require 'jsduck/web/writer'
+require 'jsduck/logger'
 
 module JsDuck
 
@@ -15,6 +16,7 @@ module JsDuck
     end
 
     # Main App logic.
+    # Returns application exit code.
     def run
       parse
 
@@ -25,6 +27,12 @@ module JsDuck
       else
         generate_web_page
       end
+
+      if @opts.warnings_exit_nonzero && Logger.warnings_logged?
+        return 2
+      else
+        return 0
+      end
     end
 
     private

data/lib/jsduck/assets.rb

@@ -6,6 +6,7 @@ require 'jsduck/videos'
 require 'jsduck/examples'
 require 'jsduck/categories/factory'
 require 'jsduck/format/doc'
+require 'jsduck/news'
 
 module JsDuck
 
@@ -22,6 +23,7 @@ module JsDuck
     attr_reader :videos
     attr_reader :examples
     attr_reader :categories
+    attr_reader :news
 
     def initialize(relations, opts)
       @relations = relations
@@ -35,6 +37,7 @@ module JsDuck
       @videos = Videos.create(@opts.videos)
       @examples = Examples.create(@opts.examples, @opts)
       @categories = Categories::Factory.create(@opts.categories_path, doc_formatter, @relations)
+      @news = News.create(@relations, doc_formatter, @opts)
     end
 
     # Writes out the assets that can be written out separately:

data/lib/jsduck/batch_processor.rb

@@ -12,6 +12,7 @@ require 'jsduck/process/overrides'
 require 'jsduck/process/inherit_doc'
 require 'jsduck/process/versions'
 require 'jsduck/process/return_values'
+require 'jsduck/process/fires'
 require 'jsduck/process/lint'
 require 'jsduck/process/circular_deps'
 
@@ -68,6 +69,7 @@ module JsDuck
       Process::InheritDoc.new(relations).process_all!
       Process::Versions.new(relations, opts).process_all!
       Process::ReturnValues.new(relations).process_all!
+      Process::Fires.new(relations).process_all!
       Process::Lint.new(relations).process_all!
       relations
     end

data/lib/jsduck/categories/class_name.rb

@@ -27,36 +27,12 @@ module JsDuck
       # Adds small star to new classes in the current version.
       def render_new_label(cls)
         if cls[:new]
-          "&nbsp;<span class='new-class' title='New class'>#{stars(1)}</span>"
+          "&nbsp;<span class='new-class' title='New class'>&#9733;</span>"
         else
-          n = new_members_count(cls)
-          if n > 0
-            title = "#{n} new member#{(n>1) ? 's' : ''}"
-            "&nbsp;<span class='new-members' title='#{title}'>#{stars(n)}</span>"
-          else
-            ""
-          end
+          ""
         end
       end
 
-      # Produces string of n stars.
-      # First 3 stars are rendered as "<unicode-star>", the following as "+".
-      # At max 15 stars are rendered.
-      def stars(n)
-        if n > 15
-          stars(3) + ("+" * (15-3))
-        elsif n > 3
-          stars(3) + ("+" * (n-3))
-        else
-          "&#9733;" * n
-        end
-      end
-
-      # Returns number of new members the class has in the current version
-      def new_members_count(cls)
-        cls.find_members(:local => true).find_all {|m| m[:new] && !m[:private] }.length
-      end
-
     end
 
   end

data/lib/jsduck/categories/factory.rb

@@ -2,6 +2,7 @@ require 'jsduck/logger'
 require 'jsduck/categories/file'
 require 'jsduck/categories/auto'
 require 'jsduck/categories/class_name'
+require 'jsduck/columns'
 
 module JsDuck
   module Categories
@@ -20,6 +21,7 @@ module JsDuck
       def initialize(categories, doc_formatter, relations={})
         @categories = categories
         @class_name = Categories::ClassName.new(doc_formatter, relations)
+        @columns = Columns.new("classes")
       end
 
       # Returns HTML listing of classes divided into categories
@@ -41,10 +43,12 @@ module JsDuck
         EOHTML
       end
 
+      private
+
       def render_columns(groups)
         align = ["left-column", "middle-column", "right-column"]
         i = -1
-        return split(groups, 3).map do |col|
+        return @columns.split(groups, 3).map do |col|
           i += 1
           [
             "<div class='#{align[i]}'>",
@@ -65,48 +69,6 @@ module JsDuck
         end
       end
 
-      # Splits the array of items into n chunks so that the sum of
-      # largest chunk is as small as possible.
-      #
-      # This is a brute-force implementation - we just try all the
-      # combinations and choose the best one.
-      def split(items, n)
-        if n == 1
-          [items]
-        elsif items.length <= n
-          Array.new(n) {|i| items[i] ? [items[i]] : [] }
-        else
-          min_max = nil
-          min_arr = nil
-          i = 0
-          while i <= items.length-n
-            i += 1
-            # Try placing 1, 2, 3, ... items to first chunk.
-            # Calculate the remaining chunks recursively.
-            cols = [items[0,i]] + split(items[i, items.length], n-1)
-            max = max_sum(cols)
-            # Is this the optimal solution so far? Remember it.
-            if !min_max || max < min_max
-              min_max = max
-              min_arr = cols
-            end
-          end
-          min_arr
-        end
-      end
-
-      def max_sum(cols)
-        cols.map {|col| sum(col) }.max
-      end
-
-      # Finds the total size of items in array
-      #
-      # The size of one item is it's number of classes + the space for header
-      def sum(arr)
-        header_size = 3
-        arr.reduce(0) {|sum, item| sum + item["classes"].length + header_size }
-      end
-
     end
 
   end

data/lib/jsduck/columns.rb

@@ -0,0 +1,56 @@
+module JsDuck
+
+  # Splits array of items with subitems into roughly equal size groups.
+  class Columns
+    # Initialized with the name of subitems field.
+    def initialize(subitems_field)
+      @header_size = 3
+      @subitems_field = subitems_field
+    end
+
+    # Splits the array of items into n chunks so that the sum of
+    # largest chunk is as small as possible.
+    #
+    # This is a brute-force implementation - we just try all the
+    # combinations and choose the best one.
+    def split(items, n)
+      if n == 1
+        [items]
+      elsif items.length <= n
+        Array.new(n) {|i| items[i] ? [items[i]] : [] }
+      else
+        min_max = nil
+        min_arr = nil
+        i = 0
+        while i <= items.length-n
+          i += 1
+          # Try placing 1, 2, 3, ... items to first chunk.
+          # Calculate the remaining chunks recursively.
+          cols = [items[0,i]] + split(items[i, items.length], n-1)
+          max = max_sum(cols)
+          # Is this the optimal solution so far? Remember it.
+          if !min_max || max < min_max
+            min_max = max
+            min_arr = cols
+          end
+        end
+        min_arr
+      end
+    end
+
+    private
+
+    def max_sum(cols)
+      cols.map {|col| sum(col) }.max
+    end
+
+    # Finds the total size of items in array
+    #
+    # The size of one item is it's number of classes + the space for header
+    def sum(arr)
+      arr.reduce(0) {|sum, item| sum + item[@subitems_field].length + @header_size }
+    end
+
+  end
+
+end

data/lib/jsduck/doc/delimited_parser.rb

@@ -0,0 +1,105 @@
+module JsDuck
+  module Doc
+
+    # Helper in parsing the default values and type definitions where
+    # we take into account correctly nested parenthesis and strings.
+    # But at the same time we don't care much about the actual
+    # contents.
+    class DelimitedParser
+      # Initialized with Doc::Scanner instance
+      def initialize(doc_scanner)
+        @ds = doc_scanner
+      end
+
+      # Parses until a closing "}".
+      def parse_until_close_curly
+        parse_until_close_paren(/\}/, /[^\}]*/)
+      end
+
+      # Parses until a closing "]".
+      def parse_until_close_square
+        parse_until_close_paren(/\]/, /[^\]]*/)
+      end
+
+      # Parses until a closing parenthesis or space.
+      def parse_until_space
+        begin
+          parse_while(/[^\[\]\{\}\(\)'"\s]/)
+        rescue
+          nil
+        end
+      end
+
+      private
+
+      # Parses until a given closing parenthesis.
+      # When unsuccessful, try simple parsing.
+      def parse_until_close_paren(re_paren, re_simple)
+        begin
+          start_pos = @ds.input.pos
+          result = parse_while(/[^\[\]\{\}\(\)'"]/)
+          if look(re_paren)
+            result
+          else
+            throw "Closing brace expected"
+          end
+        rescue
+          @ds.input.pos = start_pos
+          match(re_simple)
+        end
+      end
+
+      def parse_while(regex)
+        result = ""
+        while r = parse_compound || match(regex)
+          result += r
+        end
+        result
+      end
+
+      def parse_compound
+        if look(/\[/)
+          parse_balanced(/\[/, /\]/)
+        elsif look(/\{/)
+          parse_balanced(/\{/, /\}/)
+        elsif look(/\(/)
+          parse_balanced(/\(/, /\)/)
+        elsif look(/"/)
+          parse_string('"')
+        elsif look(/'/)
+          parse_string("'")
+        end
+      end
+
+      def parse_balanced(re_open, re_close)
+        result = match(re_open)
+
+        result += parse_while(/[^\[\]\{\}\(\)'"]/)
+
+        if r = match(re_close)
+          result + r
+        else
+          throw "Unbalanced parenthesis"
+        end
+      end
+
+      # Parses "..." or '...' including the escape sequence \' or '\"
+      def parse_string(quote)
+        re_quote = Regexp.new(quote)
+        re_rest = Regexp.new("(?:[^"+quote+"\\\\]|\\\\.)*")
+        match(re_quote) + match(re_rest) + (match(re_quote) || "")
+      end
+
+      ### Forward these calls to Doc::Scanner
+
+      def look(re)
+        @ds.look(re)
+      end
+
+      def match(re)
+        @ds.match(re)
+      end
+    end
+
+  end
+end

data/lib/jsduck/doc/scanner.rb

@@ -1,4 +1,5 @@
 require 'jsduck/doc/standard_tag_parser'
+require 'jsduck/logger'
 
 module JsDuck
   module Doc
@@ -20,7 +21,7 @@ module JsDuck
       end
 
       # Provides access to StringScanner
-      attr_reader :input
+      attr_accessor :input
 
       # Parses standard pattern common in several builtin tags, which
       # goes like this:

data/lib/jsduck/doc/standard_tag_parser.rb

@@ -1,3 +1,5 @@
+require 'jsduck/doc/delimited_parser'
+
 module JsDuck
   module Doc
 
@@ -10,6 +12,7 @@ module JsDuck
       # Initialized with Doc::Scanner instance
       def initialize(doc_scanner)
         @ds = doc_scanner
+        @delimited_parser = Doc::DelimitedParser.new(doc_scanner)
       end
 
       # Parses the standard tag pattern.
@@ -19,21 +22,25 @@ module JsDuck
       #
       # - :tagname => The :tagname of the hash to return.
       #
-      # - :type => True to parse {Type} section.
-      #            Produces :type and :optional keys.
+      # - :type => True to parse `{Type}` section.
+      #
+      # - :name => True to parse `some.name` section.
+      #
+      # - :default => True to parse `=<default-value>` after name.
       #
-      # - :name => Trye to parse [some.name=default] section.
-      #            Produces :name, :default and :optional keys.
+      # - :optional => True to allow placing name and default value
+      #       inside [ and ] brackets to denote optionality.
+      #       Also returns :optional=>true when {SomType=} syntax used.
       #
-      # Returns tag definition hash containing the given :tagname and a
-      # set of other fields depending on whether :type and :name configs
-      # were specified and how their matching succeeded.
+      # Returns tag definition hash containing the fields specified by
+      # config.
       #
       def parse(cfg)
         @tagname = cfg[:tagname]
-        tag = {:tagname => cfg[:tagname]}
-        add_type(tag) if cfg[:type]
-        add_name_with_default(tag) if cfg[:name]
+        tag = {}
+        tag[:tagname] = cfg[:tagname] if cfg[:tagname]
+        add_type(tag, cfg) if cfg[:type]
+        add_name_with_default(tag, cfg) if cfg[:name]
         tag
       end
 
@@ -41,11 +48,11 @@ module JsDuck
 
       # matches {type} if possible and sets it on given tag hash.
       # Also checks for {optionality=} in type definition.
-      def add_type(tag)
+      def add_type(tag, cfg)
         if hw.look(/\{/)
           tdf = typedef
           tag[:type] = tdf[:type]
-          tag[:optional] = true if tdf[:optional]
+          tag[:optional] = true if tdf[:optional] && cfg[:optional]
         end
       end
 
@@ -53,7 +60,11 @@ module JsDuck
       def typedef
         match(/\{/)
 
-        name = parse_balanced(/\{/, /\}/, /[^{}'"]*/)
+        name = @delimited_parser.parse_until_close_curly
+
+        unless match(/\}/)
+          warn("@#{@tagname} tag syntax: '}' expected")
+        end
 
         if name =~ /=$/
           name = name.chop
@@ -62,74 +73,29 @@ module JsDuck
           optional = nil
         end
 
-        match(/\}/) or warn("@#{@tagname} tag syntax: '}' expected")
-
         return {:type => name, :optional => optional}
       end
 
-      # matches: <ident-chain> | "[" <ident-chain> [ "=" <default-value> ] "]"
-      def add_name_with_default(tag)
-        if hw.match(/\[/)
+      # matches:   <ident-chain>
+      #          | <ident-chain> [ "=" <default-value>
+      #          | "[" <ident-chain> [ "=" <default-value> ] "]"
+      def add_name_with_default(tag, cfg)
+        if hw.look(/\[/) && cfg[:optional]
+          match(/\[/)
           tag[:name] = hw.ident_chain
           if hw.match(/=/)
             hw
-            tag[:default] = default_value
+            tag[:default] = @delimited_parser.parse_until_close_square
           end
           hw.match(/\]/) or warn("@#{@tagname} tag syntax: ']' expected")
           tag[:optional] = true
-        else
-          tag[:name] = hw.ident_chain
-        end
-      end
-
-      # 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 = @ds.input.pos
-        value = parse_balanced(/\[/, /\]/, /[^\[\]'"]*/)
-        if look(/\]/)
-          value
-        else
-          @ds.input.pos = start_pos
-          match(/[^\]]*/)
-        end
-      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 and strings
-      def parse_balanced(re_open, re_close, re_rest)
-        result = parse_with_strings(re_rest)
-        while look(re_open)
-          result += match(re_open)
-          result += parse_balanced(re_open, re_close, re_rest)
-          result += match(re_close)
-          result += parse_with_strings(re_rest)
-        end
-        result
-      end
-
-      # Helper for parse_balanced to parse rest of the text between
-      # braces, taking account the strings which might occur there.
-      def parse_with_strings(re_rest)
-        result = match(re_rest)
-        while look(/['"]/)
-          result += parse_string('"') if look(/"/)
-          result += parse_string("'") if look(/'/)
-          result += match(re_rest)
+        elsif name = ident_chain
+          tag[:name] = name
+          if cfg[:default] && hw.match(/=/)
+            hw
+            tag[:default] = @delimited_parser.parse_until_space
+          end
         end
-        result
-      end
-
-      # Parses "..." or '...' including the escape sequence \' or '\"
-      def parse_string(quote)
-        re_quote = Regexp.new(quote)
-        re_rest = Regexp.new("(?:[^"+quote+"\\\\]|\\\\.)*")
-        match(re_quote) + match(re_rest) + (match(re_quote) || "")
       end
 
       ### Forward these calls to Doc::Scanner