jsduck 0.4 → 0.5

data/README.md

@@ -117,26 +117,35 @@ JsDuck depends on [json][], [RDiscount][], and [parallel][] plus [RSpec][] for t
 Usage
 -----
 
-Just call it from command line with output directory and a list of
-JavaScript files:
+Just call it from command line with output directory and a directory
+containing your JavaScript files:
 
-    $ jsduck --verbose --output some/dir  your/project/*.js
+    $ jsduck --verbose --output some/dir  your/project/js
 
-To specify a lot of files you should probably create a script that
-generates a file list and passes it through `xargs` to `jsduck`.
+The `--verbose` flag creates a lot of output, but at least you will
+see that something is happening.
 
-For example to generate documentation for ExtJS:
+You pass in both directories and JavaScript files.  For example to
+generate docs for ExtJS 3, the simplest way is the following:
 
-    $ find ext-3.3.1/src/ -name '*.js' | egrep -v 'locale/|test/|adapter/' | xargs jsduck -v -o output/
+    $ jsduck -v -o output/ ext-3.3.1/src/
 
-The `--verbose` flag creates a lot of output, but at least you will
-see that something is happening.
+But this will give you a bunch of warnings, so you should better
+create a script that takes just the files really needed and passes
+them through `xargs` to `jsduck`:
 
-Here's how the resulting documentation will look:
+    $ find ext-3.3.1/src/ -name '*.js' | egrep -v 'locale/|test/|adapter/' | xargs jsduck -v -o output/
+
+Here's how the resulting documentation will look (ExtJS 3.3.1):
 
 * [JsDuck generated documentation](http://triin.net/temp/jsduck/)
 * [Official ExtJS documentation](http://dev.sencha.com/deploy/dev/docs/) (for comparison)
 
+Here's the same for ExtJS 4 Preview 5:
+
+* [JsDuck generated documentation](http://triin.net/temp/jsduck4/)
+* [Official ExtJS documentation](http://dev.sencha.com/deploy/ext-4.0-pr5/docs/) (for comparison)
+
 
 Documentation
 -------------
@@ -178,8 +187,6 @@ missing.
 Missing features and TODO
 -------------------------
 
-* Search, not just searching from official ExtJS documentation.
-
 * Support for custom @tags. Ext-doc supports this, I personally have
   never used this feature, so I'm thinking it's not really needed.
 
@@ -189,12 +196,21 @@ Copying
 
 JsDuck is distributed under the terms of the GNU General Public License version 3.
 
-JsDuck was developed by [Rene Saarsoo](http://triin.net).
+JsDuck was developed by [Rene Saarsoo](http://triin.net),
+with contributions from [Ondřej Jirman](https://github.com/megous).
 
 
 Changelog
 ---------
 
+* 0.5 - Search and export
+  * Search from the actually generated docs (not through sencha.com)
+  * JSON export with --json switch.
+  * Listing of mixed into classes.
+  * Option to control or disable parallel processing.
+  * Accepting directories as input (those are scanned for .js files)
+  * Many bug fixes.
+
 * 0.4 - Ext4 support
   * Support for Ext.define() syntax from ExtJS 4.
   * Showing @xtype and @author information on generated pages.

data/Rakefile

@@ -3,11 +3,11 @@ require 'rake'
 
 $LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
 
-require 'spec'
-require 'spec/rake/spectask'
-Spec::Rake::SpecTask.new(:spec) do |spec|
-  spec.spec_opts = ["--color"]
-  spec.spec_files = FileList["spec/**/*_spec.rb"]
+require 'rspec'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.rspec_opts = ["--color"]
+  spec.pattern = "spec/**/*_spec.rb"
 end
 
 desc "Build gem locally"

data/bin/jsduck

@@ -24,7 +24,7 @@ app = JsDuck::App.new
 app.template_dir = File.dirname(File.dirname(__FILE__)) + "/template"
 
 opts = OptionParser.new do | opts |
-  opts.banner = "Usage: jsduck [options] files..."
+  opts.banner = "Usage: jsduck [options] files/dirs..."
 
   opts.on('-o', '--output=PATH', "Directory to output all this amazing documentation.") do |path|
     app.output_dir = path
@@ -34,6 +34,17 @@ opts = OptionParser.new do | opts |
     app.template_dir = path
   end
 
+  opts.on('--json', "Produces JSON export instead of HTML documentation.") do |path|
+    app.export = :json
+  end
+
+  # For debugging it's often useful to set --processes=0 to get deterministic results.
+  opts.on('-p', '--processes=COUNT', "The number of parallel processes to use.",
+    "Defaults to the number of processors/cores.",
+    "Set to 0 to disable parallel processing completely.") do |count|
+    app.processes = count.to_i
+  end
+
   opts.on('-v', '--verbose', "This will fill up your console.") do
     app.verbose = true
   end
@@ -44,7 +55,20 @@ opts = OptionParser.new do | opts |
   end
 end
 
-app.input_files = opts.parse!(ARGV)
+js_files = []
+# scan directories for .js files
+opts.parse!(ARGV).each do |fname|
+  if File.exists?(fname)
+    if File.directory?(fname)
+      Dir[fname+"/**/*.js"].each {|f| js_files << f }
+    else
+      js_files << fname
+    end
+  else
+    puts "Warning: File #{fname} not found"
+  end
+end
+app.input_files = js_files
 
 if app.input_files.length == 0
   puts "You should specify some input files, otherwise there's nothing I can do :("

data/jsduck.gemspec

@@ -2,8 +2,8 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = ">= 1.3.7"
 
   s.name = 'jsduck'
-  s.version = '0.4'
-  s.date = '2011-02-28'
+  s.version = '0.5'
+  s.date = '2011-03-29'
   s.summary = "Simple JavaScript Duckumentation generator"
   s.description = "Better ext-doc like JavaScript documentation generator for ExtJS"
   s.homepage = "https://github.com/nene/jsduck"

data/lib/jsduck/app.rb

@@ -5,12 +5,14 @@ require 'jsduck/source_formatter'
 require 'jsduck/class'
 require 'jsduck/tree'
 require 'jsduck/tree_icons'
-require 'jsduck/subclasses'
+require 'jsduck/members'
+require 'jsduck/relations'
 require 'jsduck/page'
+require 'jsduck/exporter'
 require 'jsduck/timer'
+require 'jsduck/parallel_wrap'
 require 'json'
 require 'fileutils'
-require 'parallel'
 
 module JsDuck
 
@@ -21,32 +23,53 @@ module JsDuck
     attr_accessor :template_dir
     attr_accessor :input_files
     attr_accessor :verbose
+    attr_accessor :export
 
     def initialize
       @output_dir = nil
       @template_dir = nil
       @input_files = []
       @verbose = false
+      @export = nil
       @timer = Timer.new
+      @parallel = ParallelWrap.new
+    end
+
+    # Sets the nr of parallel processes to use.
+    # Set to 0 to disable parallelization completely.
+    def processes=(count)
+      @parallel = ParallelWrap.new(:in_processes => count)
     end
 
     # Call this after input parameters set
     def run
-      copy_template(@template_dir, @output_dir)
+      clear_dir(@output_dir)
+      if @export
+        FileUtils.mkdir(@output_dir)
+        init_output_dirs(@output_dir)
+      else
+        copy_template(@template_dir, @output_dir)
+      end
 
       parsed_files = @timer.time(:parsing) { parallel_parse(@input_files) }
       result = @timer.time(:aggregating) { aggregate(parsed_files) }
-      classes = @timer.time(:aggregating) { filter_classes(result) }
-      @timer.time(:generating) { write_tree(@output_dir+"/output/tree.js", classes) }
-      @timer.time(:generating) { write_pages(@output_dir+"/output", classes) }
+      relations = @timer.time(:aggregating) { filter_classes(result) }
+
+      if @export == :json
+        @timer.time(:generating) { write_json(@output_dir+"/output", relations) }
+      else
+        @timer.time(:generating) { write_tree(@output_dir+"/output/tree.js", relations) }
+        @timer.time(:generating) { write_members(@output_dir+"/output/members.js", relations) }
+        @timer.time(:generating) { write_pages(@output_dir+"/output", relations) }
+      end
 
       @timer.report if @verbose
     end
 
     # Parses the files in parallel using as many processes as available CPU-s
     def parallel_parse(filenames)
-      src = SourceFormatter.new(@output_dir + "/source")
-      Parallel.map(filenames) do |fname|
+      src = SourceFormatter.new(@output_dir + "/source", @export ? :format_pre : :format_page)
+      @parallel.map(filenames) do |fname|
         puts "Parsing #{fname} ..." if @verbose
         code = IO.read(fname)
         {
@@ -70,10 +93,10 @@ module JsDuck
     # Filters out class-documentations, converting them to Class objects.
     # For each other type, prints a warning message and discards it
     def filter_classes(docs)
-      classes = {}
+      classes = []
       docs.each do |d|
         if d[:tagname] == :class
-          classes[d[:name]] = Class.new(d, classes)
+          classes << Class.new(d)
         else
           type = d[:tagname].to_s
           name = d[:name]
@@ -82,38 +105,64 @@ module JsDuck
           puts "Warning: Ignoring #{type}: #{name} in #{file} line #{line}"
         end
       end
-      classes.values
+      Relations.new(classes)
     end
 
-    # Given array of doc-objects, generates namespace tree and writes in
+    # Given all classes, generates namespace tree and writes it
     # in JSON form into a file.
-    def write_tree(filename, docs)
-      tree = Tree.new.create(docs)
+    def write_tree(filename, relations)
+      tree = Tree.new.create(relations.classes)
       icons = TreeIcons.new.extract_icons(tree)
       js = "Docs.classData = " + JSON.generate( tree ) + ";"
       js += "Docs.icons = " + JSON.generate( icons ) + ";"
       File.open(filename, 'w') {|f| f.write(js) }
     end
 
+    # Given all classes, generates members data for search and writes in
+    # in JSON form into a file.
+    def write_members(filename, relations)
+      members = Members.new.create(relations.classes)
+      js = "Docs.membersData = " + JSON.generate( {:data => members} ) + ";"
+      File.open(filename, 'w') {|f| f.write(js) }
+    end
+
     # Writes documentation page for each class
     # We do it in parallel using as many processes as available CPU-s
-    def write_pages(path, docs)
-      subclasses = Subclasses.new(docs)
+    def write_pages(path, relations)
       cache = {}
-      Parallel.each(docs) do |cls|
+      @parallel.each(relations.classes) do |cls|
         filename = path + "/" + cls[:name] + ".html"
         puts "Writing to #{filename} ..." if @verbose
-        html = Page.new(cls, subclasses, cache).to_html
+        html = Page.new(cls, relations, cache).to_html
         File.open(filename, 'w') {|f| f.write(html) }
       end
     end
 
+    # Writes JSON export file for each class
+    def write_json(path, relations)
+      exporter = Exporter.new(relations)
+      @parallel.each(relations.classes) do |cls|
+        filename = path + "/" + cls[:name] + ".json"
+        puts "Writing to #{filename} ..." if @verbose
+        hash = exporter.export(cls)
+        json = JSON.pretty_generate(hash)
+        File.open(filename, 'w') {|f| f.write(json) }
+      end
+    end
+
     def copy_template(template_dir, dir)
       puts "Copying template files to #{dir}..." if @verbose
+      FileUtils.cp_r(template_dir, dir)
+      init_output_dirs(dir)
+    end
+
+    def clear_dir(dir)
       if File.exists?(dir)
         FileUtils.rm_r(dir)
       end
-      FileUtils.cp_r(template_dir, dir)
+    end
+
+    def init_output_dirs(dir)
       FileUtils.mkdir(dir + "/output")
       FileUtils.mkdir(dir + "/source")
     end

data/lib/jsduck/class.rb

@@ -4,9 +4,11 @@ module JsDuck
   # methods on it.  Otherwise it acts like Hash, providing the []
   # method.
   class Class
-    def initialize(doc, classes={})
+    attr_accessor :relations
+
+    def initialize(doc)
       @doc = doc
-      @classes = classes
+      @relations = nil
     end
 
     def [](key)
@@ -15,13 +17,38 @@ module JsDuck
 
     # Returns instance of parent class, or nil if there is none
     def parent
-      @doc[:extends] ? @classes[@doc[:extends]] : nil
+      @doc[:extends] ? lookup(@doc[:extends]) : nil
+    end
+
+    # Returns array of ancestor classes.
+    # Example result when asking ancestors of MyPanel might be:
+    #
+    #   [Ext.util.Observable, Ext.Component, Ext.Panel]
+    #
+    def superclasses
+      p = parent
+      p ? p.superclasses + [p]  : []
     end
 
     # Returns array of mixin class instances.
     # Returns empty array if no mixins
     def mixins
-      @doc[:mixins] ? @doc[:mixins].collect {|classname| @classes[classname] } : []
+      @doc[:mixins] ? @doc[:mixins].collect {|classname| lookup(classname) }.compact : []
+    end
+
+    # Looks up class object by name
+    # When not found, prints warning message.
+    def lookup(classname)
+      if @relations[classname]
+        @relations[classname]
+      elsif classname != "Object"
+        puts "Warning: Class #{classname} not found in #{@doc[:filename]} line #{@doc[:linenr]}"
+      end
+    end
+
+    # Returns copy of @doc hash
+    def to_hash
+      @doc.clone
     end
 
     # Returns true when this class inherits from the specified class.

data/lib/jsduck/doc_formatter.rb

@@ -5,11 +5,27 @@ module JsDuck
 
   # Formats doc-comments
   class DocFormatter
-    # Initializes instance to work in context of particular class, so
+    # CSS class to add to each link
+    attr_accessor :css_class
+
+    # Template for the href URL.
+    # Can contain %cls% which is replaced with actual classname.
+    # Also '#' and member name is appended to link if needed
+    attr_accessor :url_template
+
+    # Sets up instance to work in context of particular class, so
     # that when {@link #blah} is encountered it knows that
     # Context#blah is meant.
-    def initialize(context)
-      @context = context
+    attr_accessor :context
+
+    # Maximum length for text that doesn't get shortened, defaults to 120
+    attr_accessor :max_length
+
+    def initialize
+      @context = ""
+      @css_class = nil
+      @url_template = "%cls%"
+      @max_length = 120
     end
 
     # Replaces {@link Class#member link text} in given string with
@@ -17,7 +33,7 @@ module JsDuck
     # attribute links will also contain ext:cls and ext:member
     # attributes.
     def replace(input)
-      input.gsub(/\{@link +(\S*?)(?: +(.+?))?\}/) do
+      input.gsub(/\{@link\s+(\S*?)(?:\s+(.+?))?\}/m) do
         target = $1
         text = $2
         if target =~ /^(.*)#(.*)$/
@@ -28,11 +44,6 @@ module JsDuck
           member = false
         end
 
-        # Construct link attributes
-        href = " href=\"output/#{cls}.html" + (member ? "#" + cls + "-" + member : "") + '"'
-        ext_cls = ' ext:cls="' + cls + '"'
-        ext_member = member ? ' ext:member="' + member + '"' : ""
-
         # Construct link text
         if text
           text = text
@@ -42,10 +53,20 @@ module JsDuck
           text = cls
         end
 
-        "<a" + href + ext_cls + ext_member + ">" + text + "</a>"
+        link(cls, member, text)
       end
     end
 
+    # Creates HTML link to class and/or member
+    def link(cls, member, label)
+      anchor = member ? "#" + member : ""
+      url = @url_template.sub(/%cls%/, cls) + anchor
+      href = ' href="' + url + '"'
+      rel = ' rel="' + cls + anchor + '"'
+      cssCls = @css_class ? ' class="' + @css_class + '"' : ''
+      "<a" + href + rel + cssCls + ">" + label + "</a>"
+    end
+
     # Formats doc-comment for placement into HTML.
     # Renders it with Markdown-formatter and replaces @link-s.
     def format(input)
@@ -64,6 +85,36 @@ module JsDuck
       replace(RDiscount.new(input).to_html)
     end
 
+    # Shortens text if needed.
+    #
+    # 116 chars is also where ext-doc makes its cut, but unlike
+    # ext-doc we only make the cut when there's more than 120 chars.
+    #
+    # This way we don't get stupid expansions like:
+    #
+    #   Blah blah blah some text...
+    #
+    # expanding to:
+    #
+    #   Blah blah blah some text.
+    #
+    # Ellipsis is only added when input actually gets shortened.
+    def shorten(input)
+      if too_long?(input)
+        strip_tags(input)[0..(@max_length-4)] + "..."
+      else
+        input
+      end
+    end
+
+    # Returns true when input should get shortened.
+    def too_long?(input)
+      strip_tags(input).length > @max_length
+    end
+
+    def strip_tags(str)
+      str.gsub(/<.*?>/, "")
+    end
   end
 
 end

data/lib/jsduck/doc_parser.rb

@@ -200,7 +200,7 @@ module JsDuck
     def at_xtype
       match(/@xtype/)
       add_tag(:xtype)
-      maybe_name
+      maybe_ident_chain(:name)
       skip_white
     end
 

data/lib/jsduck/exporter.rb

@@ -0,0 +1,75 @@
+require 'jsduck/doc_formatter'
+
+module JsDuck
+
+  # Export class data as hash with :cfg being replace with :cfgs and
+  # including all the inherited members too.  Same for :properties,
+  # :methods, and :events.
+  #
+  # Also all the :doc elements will be formatted - converted from
+  # markdown to HTML and @links resolved.
+  class Exporter
+    attr_accessor :relations
+
+    def initialize(relations)
+      @relations = relations
+      @formatter = DocFormatter.new
+      @formatter.css_class = 'docClass'
+    end
+
+    # Returns all data in Class object as hash.
+    def export(cls)
+      h = cls.to_hash
+      h[:cfgs] = cls.members(:cfg)
+      h[:properties] = cls.members(:property)
+      h[:methods] = cls.members(:method)
+      h[:events] = cls.members(:event)
+      h.delete(:cfg)
+      h.delete(:property)
+      h.delete(:method)
+      h.delete(:event)
+      h[:component] = cls.inherits_from?("Ext.Component")
+      h[:superclasses] = cls.superclasses.collect {|c| c.full_name }
+      h[:subclasses] = @relations.subclasses(cls).collect {|c| c.full_name }
+      h[:mixedInto] = @relations.mixed_into(cls).collect {|c| c.full_name }
+      format_class(h)
+    end
+
+    # converts :doc properties from markdown to html and resolve @links
+    def format_class(c)
+      @formatter.context = c[:name]
+      c[:doc] = @formatter.format(c[:doc]) if c[:doc]
+      [:cfgs, :properties, :methods, :events].each do |type|
+        c[type] = c[type].map {|m| format_member(m) }
+      end
+      c
+    end
+
+    def format_member(m)
+      m = m.clone
+      m[:doc] = @formatter.format(m[:doc]) if m[:doc]
+      if m[:params] || @formatter.too_long?(m[:doc])
+        m[:shortDoc] = @formatter.shorten(m[:doc])
+      end
+      m[:params] = format_params(m[:params]) if m[:params]
+      m[:return] = format_return(m[:return]) if m[:return]
+      m
+    end
+
+    def format_params(params)
+      params.map do |p|
+        p = p.clone
+        p[:doc] = @formatter.format(p[:doc]) if p[:doc]
+        p
+      end
+    end
+
+    def format_return(r)
+      r = r.clone
+      r[:doc] = @formatter.format(r[:doc]) if r[:doc]
+      r
+    end
+
+  end
+
+end

data/lib/jsduck/inheritance_tree.rb

@@ -1,15 +1,21 @@
+require 'jsduck/doc_formatter'
+
 module JsDuck
 
   # Creates the inheritance tree shown on class documentation page.
   class InheritanceTree
     def initialize(cls)
       @cls = cls
+      @formatter = DocFormatter.new
+      @formatter.context = cls.full_name
+      @formatter.css_class = 'docClass'
+      @formatter.url_template = 'output/%cls%.html'
     end
 
     # Renders the tree using HTML <pre> element
     def to_html
       i = -1
-      html = ancestors(@cls).reverse.collect do |cls|
+      html = (@cls.superclasses + [@cls]).collect do |cls|
         i += 1
         make_indent(i) + make_link(cls)
       end.join("\n")
@@ -21,16 +27,6 @@ module JsDuck
       EOHTML
     end
 
-    # Returns array of the names of ancestor classes for given class.
-    # Including the name of the class itself.
-    # Example result when ascing ancestors of MyPanel might be:
-    #
-    #   [MyPanel, Ext.Panel, Ext.Component, Ext.util.Observable]
-    #
-    def ancestors(cls)
-      cls.parent ? [cls] + ancestors(cls.parent) : [cls]
-    end
-
     def make_indent(level)
       if level > 0
         ("  " * level) + "<img src='resources/elbow-end.gif' alt=''>"
@@ -43,7 +39,7 @@ module JsDuck
       if cls == @cls
         cls.short_name
       else
-        "<a href='output/#{cls.full_name}.html' ext:cls='#{cls.full_name}'>#{cls.short_name}</a>"
+        @formatter.link(cls.full_name, nil, cls.short_name)
       end
     end
   end

data/lib/jsduck/lexer.rb

@@ -97,12 +97,12 @@ module JsDuck
         elsif @input.check(/'/)
           @tokens << {
             :type => :string,
-            :value => eval(@input.scan(/'([^'\\]|\\.)*'/))
+            :value => @input.scan(/'([^'\\]|\\.)*'/).sub(/^'(.*)'$/, "\\1")
           }
         elsif @input.check(/"/)
           @tokens << {
             :type => :string,
-            :value => eval(@input.scan(/"([^"\\]|\\.)*"/))
+            :value => @input.scan(/"([^"\\]|\\.)*"/).sub(/^"(.*)"$/, "\\1")
           }
         elsif @input.check(/\//)
           # Several things begin with dash:

data/lib/jsduck/long_params.rb

@@ -6,7 +6,10 @@ module JsDuck
   # for use in documentation body.
   class LongParams
     def initialize(cls)
-      @formatter = DocFormatter.new(cls.full_name)
+      @formatter = DocFormatter.new()
+      @formatter.context = cls.full_name
+      @formatter.css_class = 'docClass'
+      @formatter.url_template = 'output/%cls%.html'
     end
 
     def render(params)

data/lib/jsduck/members.rb

@@ -0,0 +1,57 @@
+
+module JsDuck
+
+  # Creates list of all members in all classes that is used by the
+  # searching feature in UI.
+  class Members
+    # Given list of class documentation objects returns an array of
+    # hashes describing all the members.
+    def create(docs)
+      list = []
+      docs.each do |cls|
+        [:cfg, :property, :method, :event].each do |type|
+          cls.members(type).each do |m|
+            list << member_node(m, cls)
+          end
+        end
+      end
+      list
+    end
+
+    # Creates structure representing one member
+    def member_node(member, cls)
+      return {
+        :cls => cls.full_name,
+        :member => member[:name],
+        :type => member[:tagname],
+        :doc => short_desc(member[:doc])
+      }
+    end
+
+    def short_desc(str)
+      tagless = first_sentence(strip_tags(strip_links(str)))
+      if tagless.length > 120
+        short_doc = tagless[0..116]
+        ellipsis = tagless.length > short_doc.length ? "..." : ""
+        tagless[0..116] + ellipsis
+      else
+        tagless
+      end
+    end
+
+    def strip_tags(str)
+      str.gsub(/<.*?>/, "")
+    end
+
+    def strip_links(str)
+      str = str.gsub(/\{@link +(\S*?)(?: +(.+?))?\}/, "\\1")
+      str = str.gsub(/#/, ".")
+    end
+
+    def first_sentence(str)
+      str.sub(/\A(.+?\.)\s.*\Z/m, "\\1")
+    end
+
+  end
+
+end

data/lib/jsduck/merger.rb

@@ -248,10 +248,13 @@ module JsDuck
       [implicit.length, explicit.length].max.times do |i|
         im = implicit[i] || {}
         ex = explicit[i] || {}
+        doc = ex[:doc] || im[:doc] || ""
         params << {
           :type => ex[:type] || im[:type] || "Object",
           :name => ex[:name] || im[:name] || "",
-          :doc => ex[:doc] || im[:doc] || "",
+          :doc => doc,
+          # convert to boolean for JavaScript export, otherwise it's 0 or nil
+          :optional => !!(doc =~ /\(optional\)/),
         }
       end
       params

data/lib/jsduck/method_table.rb

@@ -14,6 +14,10 @@ module JsDuck
       @row_class = "method-row"
       @short_params = ShortParams.new
       @long_params = LongParams.new(@cls)
+      @formatter = DocFormatter.new()
+      @formatter.context = @cls.full_name
+      @formatter.css_class = 'docClass'
+      @formatter.url_template = 'output/%cls%.html'
     end
 
     def signature_suffix(item)
@@ -33,7 +37,7 @@ module JsDuck
 
     def render_return(item)
       type = item[:return][:type]
-      doc = item[:return][:doc]
+      doc = @formatter.format(item[:return][:doc])
       if type == "void" && doc.length == 0
         "<ul><li>void</li></ul>"
       else

data/lib/jsduck/page.rb

@@ -12,14 +12,17 @@ module JsDuck
     # Initializes doc page generator
     #
     # - cls : the Class object for which to generate documentation
-    # - subclasses : lookup table for easy access to subclasses
+    # - relations : access to subclasses, mixins, etc
     # - cache : cache for already generated HTML rows for class members
     #
-    def initialize(cls, subclasses = {}, cache = {})
+    def initialize(cls, relations, cache = {})
       @cls = cls
-      @subclasses = subclasses
+      @relations = relations
       @cache = cache
-      @formatter = DocFormatter.new(cls.full_name)
+      @formatter = DocFormatter.new
+      @formatter.context = cls.full_name
+      @formatter.css_class = 'docClass'
+      @formatter.url_template = 'output/%cls%.html'
     end
 
     def to_html
@@ -50,36 +53,49 @@ module JsDuck
     def abstract
       [
        "<table cellspacing='0'>",
-        abstract_row("Extends:", @cls.parent ? class_link(@cls.parent.full_name) : "Object"),
-        @cls.mixins.length > 0 ? abstract_row("Mixins:", mixins) : "",
-        abstract_row("Defind In:", file_link),
-        @subclasses[@cls] ? abstract_row("Subclasses:", subclasses) : "",
-        @cls[:xtype] ? abstract_row("xtype:", @cls[:xtype]) : "",
-        @cls[:author] ? abstract_row("Author:", @cls[:author]) : "",
+        row("Extends:", extends_link),
+        classes_row("Mixins:", @cls.mixins),
+        row("Defind In:", file_link),
+        classes_row("Subclasses:", @relations.subclasses(@cls)),
+        classes_row("Mixed into:", @relations.mixed_into(@cls)),
+        boolean_row("xtype:", @cls[:xtype]),
+        boolean_row("Author:", @cls[:author]),
        "</table>",
       ].join("\n")
     end
 
     def class_link(class_name, label=nil)
       label = label || class_name
-      "<a href='output/#{class_name}.html' ext:cls='#{class_name}'>#{label}</a>"
+      @formatter.link(class_name, nil, label || class_name)
     end
 
     def file_link
       "<a href='source/#{@cls[:href]}'>#{File.basename(@cls[:filename])}</a>"
     end
 
-    def subclasses
-      subs = @subclasses[@cls].sort {|a, b| a.short_name <=> b.short_name }
-      subs.collect {|cls| class_link(cls.full_name, cls.short_name) }.join(", ")
+    def extends_link
+      if @cls[:extends]
+        @relations[@cls[:extends]] ? class_link(@cls[:extends]) : @cls[:extends]
+      else
+        "Object"
+      end
     end
 
-    def mixins
-      mixs = @cls.mixins.sort {|a, b| a.full_name <=> b.full_name }
-      mixs.collect {|cls| class_link(cls.full_name, cls.short_name) }.join(", ")
+    def classes_row(label, classes)
+      if classes.length > 0
+        classes = classes.sort {|a, b| a.short_name <=> b.short_name }
+        html = classes.collect {|cls| class_link(cls.full_name, cls.short_name) }.join(", ")
+        row(label, html)
+      else
+        ""
+      end
     end
 
-    def abstract_row(label, info)
+    def boolean_row(label, item)
+      item ? row(label, item) : ""
+    end
+
+    def row(label, info)
       "<tr><td class='label'>#{label}</td><td class='hd-info'>#{info}</td></tr>"
     end
 

data/lib/jsduck/parallel_wrap.rb

@@ -0,0 +1,31 @@
+require 'parallel'
+
+module JsDuck
+
+  # Wrapper around the parallel gem that falls back to simple
+  # Array#map and Array#each when :in_processes => 0 specified.
+  class ParallelWrap
+
+    # Takes config object for parallel
+    def initialize(cfg = {})
+      @cfg = cfg
+    end
+
+    def each(arr, &block)
+      if @cfg[:in_processes] == 0
+        arr.each &block
+      else
+        Parallel.each(arr, @cfg, &block)
+      end
+    end
+
+    def map(arr, &block)
+      if @cfg[:in_processes] == 0
+        arr.map &block
+      else
+        Parallel.map(arr, @cfg, &block)
+      end
+    end
+  end
+
+end

data/lib/jsduck/relations.rb

@@ -0,0 +1,68 @@
+module JsDuck
+
+  # Provides information about relations between classes.
+  #
+  # Also provides a place to look up classes by name.
+  #
+  # The constructor is initialized with array of all available
+  # classes.
+  class Relations
+    # Returns list of all classes
+    attr_reader :classes
+
+    def initialize(classes = [])
+      @classes = classes
+
+      # First build class lookup table; building lookup tables for
+      # mixins and subclasses will depend on that.
+      @lookup = {}
+      @classes.each do |cls|
+        @lookup[cls.full_name] = cls
+        cls.relations = self
+      end
+
+      @subs = {}
+      @mixes = {}
+      @classes.each do |cls|
+        reg_subclasses(cls)
+        reg_mixed_into(cls)
+      end
+    end
+
+    # Looks up class by name, nil if not found
+    def [](classname)
+      @lookup[classname]
+    end
+
+    def reg_subclasses(cls)
+      if !cls.parent
+        # do nothing
+      elsif @subs[cls.parent.full_name]
+        @subs[cls.parent.full_name] << cls
+      else
+        @subs[cls.parent.full_name] = [cls]
+      end
+    end
+
+    # Returns subclasses of particular class, empty array if none
+    def subclasses(cls)
+      @subs[cls.full_name] || []
+    end
+
+    def reg_mixed_into(cls)
+      cls.mixins.each do |mix|
+        if @mixes[mix.full_name]
+          @mixes[mix.full_name] << cls
+        else
+          @mixes[mix.full_name] = [cls]
+        end
+      end
+    end
+
+    # Returns classes having particular mixin, empty array if none
+    def mixed_into(cls)
+      @mixes[cls.full_name] || []
+    end
+  end
+
+end

data/lib/jsduck/short_params.rb

@@ -13,16 +13,12 @@ module JsDuck
 
     def render_single(param)
       str = "<code>#{param[:type]} #{param[:name]}</code>"
-      if optional?(param)
+      if param[:optional]
         "<span title='Optional' class='optional'>[" + str + "]</span>"
       else
         str
       end
     end
-
-    def optional?(param)
-      return param[:doc] =~ /\(optional\)/
-    end
   end
 
 end

data/lib/jsduck/source_formatter.rb

@@ -8,16 +8,21 @@ module JsDuck
   class SourceFormatter
 
     # Initializes SourceFormatter to the directory where
-    # HTML-formatted source files will be placed
-    def initialize(output_dir)
+    # HTML-formatted source files will be placed.
+    #
+    # formatter can be either :format_page or :format_pre; with the
+    # first one the whole HTML page is created, otherwise just a
+    # contents of <pre> element.
+    def initialize(output_dir, formatter = :format_page)
       @output_dir = output_dir
+      @formatter = formatter
     end
 
     # Converts source to HTML and writes into file in output
     # directory.  It returns the name of the file that it wrote.
     def write(source, filename)
       fname = uniq_html_filename(filename)
-      File.open(fname, 'w') {|f| f.write(format(source)) }
+      File.open(fname, 'w') {|f| f.write(self.send(@formatter, source)) }
       fname
     end
 
@@ -36,7 +41,7 @@ module JsDuck
     end
 
     # Returns full source for HTML page
-    def format(source)
+    def format_page(source)
       return <<-EOHTML
 <!DOCTYPE html>
 <html>

data/lib/jsduck/table.rb

@@ -20,7 +20,10 @@ module JsDuck
     def initialize(cls, cache={})
       @cls = cls
       @cache = cache
-      @formatter = DocFormatter.new(cls.full_name)
+      @formatter = DocFormatter.new
+      @formatter.context = cls.full_name
+      @formatter.css_class = 'docClass'
+      @formatter.url_template = 'output/%cls%.html'
     end
 
     def to_html
@@ -75,11 +78,7 @@ module JsDuck
     end
 
     def member_link(item)
-      cls = item[:member]
-      member = item[:name]
-      "<a href='output/#{cls}.html##{member}' " +
-        "ext:member='##{member}' " +
-        "ext:cls='#{cls}'>#{Class.short_name(cls)}</a>"
+      @formatter.link(item[:member], item[:name], Class.short_name(item[:member]))
     end
 
     def signature(item)
@@ -88,24 +87,11 @@ module JsDuck
       return "<a id='#{id}'></a><b><a href='#{src}'>#{item[:name]}</a></b>" + signature_suffix(item)
     end
 
-    # 116 chars is also where ext-doc makes its cut, but unlike
-    # ext-doc we only make the cut when there's more than 120 chars.
-    #
-    # This way we don't get stupid expansions like:
-    #
-    #   Blah blah blah some text...
-    #
-    # expanding to:
-    #
-    #   Blah blah blah some text.
-    #
+    # Creates either expandable or normal doc-entry
     def expandable_desc(p_doc, e_doc)
       if expandable?(p_doc, e_doc)
-        # Only show ellipsis when primary_doc is shortened.
-        tagless = strip_tags(p_doc)
-        short_doc = tagless[0..116]
-        ellipsis = tagless.length > short_doc.length ? "..." : ""
-        "<div class='short'>#{short_doc}#{ellipsis}</div>" +
+        short_doc = @formatter.shorten(p_doc)
+        "<div class='short'>#{short_doc}</div>" +
           "<div class='long'>#{p_doc}#{e_doc}</div>"
       else
         p_doc
@@ -122,11 +108,7 @@ module JsDuck
     end
 
     def expandable?(p_doc, e_doc)
-      strip_tags(p_doc).length > 120 || e_doc.length > 0
-    end
-
-    def strip_tags(str)
-      str.gsub(/<.*?>/, "")
+      @formatter.too_long?(p_doc) || e_doc.length > 0
     end
 
     def inherited?(item)

data/template/index.html

@@ -16,6 +16,7 @@
 <script type="text/javascript" src="resources/prettify/prettify.js"></script>
 <script type="text/javascript" src="resources/docs.js"></script>
 <script type="text/javascript" src="output/tree.js"></script>
+<script type="text/javascript" src="output/members.js"></script>
 </head>
 <body scroll="no" id="docs">
 

data/template/resources/docs.css

@@ -250,10 +250,12 @@ a:hover {
 .icon-event {
     background-image: url(event.gif) !important;
 }
+.icon-cfg,
 .icon-config {
     background-image: url(config.gif) !important;
 }
-.icon-prop {
+.icon-prop,
+.icon-property {
     background-image: url(prop.gif) !important;
 }
 .icon-method {

data/template/resources/docs.js

@@ -75,7 +75,7 @@ Ext.extend(ApiPanel, Ext.tree.TreePanel, {
                 handler: function(){ this.root.collapse(true); },
                 scope: this
             }]
-        })
+        });
         ApiPanel.superclass.initComponent.call(this);
     },
 	filterTree: function(t, e){
@@ -226,21 +226,20 @@ DocPanel = Ext.extend(Ext.Panel, {
 MainPanel = function(){
 	
 	this.searchStore = new Ext.data.Store({
-        proxy: new Ext.data.ScriptTagProxy({
-            url: 'http://extjs.com/playpen/api.php'
-        }),
-        reader: new Ext.data.JsonReader({
-	            root: 'data'
-	        }, 
-			['cls', 'member', 'type', 'doc']
-		),
-		baseParams: {},
-        listeners: {
-            'beforeload' : function(){
-                this.baseParams.qt = Ext.getCmp('search-type').getValue();
-            }
-        }
-    }); 
+		sortInfo: {
+			field: 'member',
+			direction: 'ASC'
+		},
+		reader: new Ext.data.JsonReader({
+			root: 'data',
+			fields: ['cls', 'member', 'type', 'doc']
+		})
+	});
+	this.searchStore.loadData(Docs.membersData);
+	this.searchStore.filterBy(function(r) {
+		return false;
+	});
+
 	
     MainPanel.superclass.constructor.call(this, {
         id:'doc-body',
@@ -256,7 +255,7 @@ MainPanel = function(){
         items: {
             id:'welcome-panel',
             title: 'API Home',
-            autoLoad: {url: 'welcome.html', callback: this.initSearch, scope: this},
+            autoLoad: {url: 'welcome.html', callback: this.initSearch, scope: this, delay: 100},
             iconCls:'icon-docs',
             autoScroll: true,
 			tbar: [
@@ -291,18 +290,17 @@ Ext.extend(MainPanel, Ext.TabPanel, {
     },
 
     onClick: function(e, target){
-        if(target = e.getTarget('a:not(.exi)', 3)){
-            var cls = Ext.fly(target).getAttributeNS('ext', 'cls');
+        if((target = e.getTarget('a:not(.exi)', 3))){
             e.stopEvent();
-            if(cls){
-                var member = Ext.fly(target).getAttributeNS('ext', 'member');
-                this.loadClass(target.href, cls, member);
+            if(/\bdocClass\b/.test(target.className)){
+                var m = target.rel.split("#");
+                this.loadClass(target.href, m[0], m[1]);
             }else if(target.className == 'inner-link'){
                 this.getActiveTab().scrollToSection(target.href.split('#')[1]);
             }else{
                 window.open(target.href);
             }
-        }else if(target = e.getTarget('.micon', 2)){
+        }else if((target = e.getTarget('.micon', 2))){
             e.stopEvent();
             var tr = Ext.fly(target.parentNode);
             if(tr.hasClass('expandable')){
@@ -343,17 +341,18 @@ Ext.extend(MainPanel, Ext.TabPanel, {
 	    var resultTpl = new Ext.XTemplate(
 	        '<tpl for=".">',
 	        '<div class="search-item">',
-	            '<a class="member" ext:cls="{cls}" ext:member="{member}" href="output/{cls}.html">',
-				'<img src="../resources/images/default/s.gif" class="item-icon icon-{type}"/>{member}',
+	            '<a class="member docClass" rel="{cls}#{member}" href="output/{cls}.html">',
+				'<img src="resources/images/default/s.gif" class="item-icon icon-{type}"/>{member}',
 				'</a> ',
-				'<a class="cls" ext:cls="{cls}" href="output/{cls}.html">{cls}</a>',
+				'<a class="cls docClass" rel="{cls}" href="output/{cls}.html">{cls}</a>',
 	            '<p>{doc}</p>',
 	        '</div></tpl>'
 	    );
-		
+
 		var p = new Ext.DataView({
-            applyTo: 'search',
+			applyTo: Ext.get('search') ? 'search' : Ext.getCmp('welcome-panel').body,
 			tpl: resultTpl,
+			deferEmptyText: false,
 			loadingText:'Searching...',
             store: this.searchStore,
             itemSelector: 'div.search-item',
@@ -452,12 +451,13 @@ Ext.app.SearchField = Ext.extend(Ext.form.TwinTriggerField, {
 
     onTrigger1Click : function(){
         if(this.hasSearch){
-            this.store.baseParams[this.paramName] = '';
-			this.store.removeAll();
-			this.el.dom.value = '';
+            this.store.filterBy(function(r) {
+                return false;
+            });
+            this.el.dom.value = '';
             this.triggers[0].hide();
             this.hasSearch = false;
-			this.focus();
+            this.focus();
         }
     },
 
@@ -471,12 +471,24 @@ Ext.app.SearchField = Ext.extend(Ext.form.TwinTriggerField, {
 			Ext.Msg.alert('Invalid Search', 'You must enter a minimum of 2 characters to search the API');
 			return;
 		}
-		this.store.baseParams[this.paramName] = v;
-        var o = {start: 0};
-        this.store.reload({params:o});
+
+		var type = Ext.getCmp('search-type').getValue();
+		this.store.filter("member", this.createRegex(type, v));
+
         this.hasSearch = true;
         this.triggers[0].show();
 		this.focus();
+    },
+
+    createRegex: function(type, text) {
+        var safeText = Ext.escapeRe(text);
+        if (type === 'Starts with') {
+            return new RegExp("^" + safeText, "i");
+        } else if (type === 'Ends with') {
+            return new RegExp(safeText + "$", "i");
+        } else {
+            return new RegExp(safeText, "i");
+        }
     }
 });
 
@@ -548,6 +560,8 @@ Ext.extend(Ext.ux.SelectBox, Ext.form.ComboBox, {
 				this.selectPrevPage();
 				e.stopEvent();
 				return;
+			default:
+				break;
 		}
 
 		// skip special keys other than the shift key

metadata

@@ -1,12 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: jsduck
 version: !ruby/object:Gem::Version 
-  hash: 3
+  hash: 1
   prerelease: false
   segments: 
   - 0
-  - 4
-  version: "0.4"
+  - 5
+  version: "0.5"
 platform: ruby
 authors: 
 - Rene Saarsoo
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-28 00:00:00 +02:00
+date: 2011-03-29 00:00:00 +03:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -81,17 +81,20 @@ files:
 - lib/jsduck/doc_formatter.rb
 - lib/jsduck/doc_parser.rb
 - lib/jsduck/event_table.rb
+- lib/jsduck/exporter.rb
 - lib/jsduck/inheritance_tree.rb
 - lib/jsduck/lexer.rb
 - lib/jsduck/long_params.rb
+- lib/jsduck/members.rb
 - lib/jsduck/merger.rb
 - lib/jsduck/method_table.rb
 - lib/jsduck/page.rb
+- lib/jsduck/parallel_wrap.rb
 - lib/jsduck/parser.rb
 - lib/jsduck/property_table.rb
+- lib/jsduck/relations.rb
 - lib/jsduck/short_params.rb
 - lib/jsduck/source_formatter.rb
-- lib/jsduck/subclasses.rb
 - lib/jsduck/table.rb
 - lib/jsduck/timer.rb
 - lib/jsduck/tree.rb

data/lib/jsduck/subclasses.rb

@@ -1,27 +0,0 @@
-module JsDuck
-
-  # Provides information about direct descendants of particular class.
-  #
-  # The constructor is initialized with array of all available
-  # classes.  Then through [] method subclasses of particlular class
-  # can be asked for.
-  class Subclasses
-    def initialize(classes)
-      @subs = {}
-      classes.each do |cls|
-        if !cls.parent
-          # do nothing
-        elsif @subs[cls.parent.full_name]
-          @subs[cls.parent.full_name] << cls
-        else
-          @subs[cls.parent.full_name] = [cls]
-        end
-      end
-    end
-
-    def [](cls)
-      @subs[cls.full_name]
-    end
-  end
-
-end