jsduck 0.5 → 0.6

data/README.md

@@ -54,7 +54,7 @@ it would like that you wrote comments like that instead:
     /**
      * Basic text field.  Can be used as a direct replacement for traditional
      * text inputs, or as the base class for more sophisticated input controls
-     * (like {@link Ext.form.TextArea} and {@link Ext.form.ComboBox}).
+     * (like Ext.form.TextArea and Ext.form.ComboBox).
      *
      * Validation
      * ----------
@@ -197,12 +197,40 @@ Copying
 JsDuck is distributed under the terms of the GNU General Public License version 3.
 
 JsDuck was developed by [Rene Saarsoo](http://triin.net),
-with contributions from [Ondřej Jirman](https://github.com/megous).
+with contributions from [Ondřej Jirman](https://github.com/megous)
+and [Nick Poulden](https://github.com/nick).
 
 
 Changelog
 ---------
 
+* 0.6 - JsDuck is now used for creating the official ExtJS4 documentation.
+  * Automatic linking of class names found in comments.  Instead of writing
+    `{@link Ext.Panel}` one can simply write `Ext.Panel` and link will be
+    automatically created.
+  * In generated docs, method return types and parameter types are also
+    automatically linked to classes if such class is included to docs.
+  * Support for `{@img}` tag for including images to documentation.
+    The markup created by `{@link}` and `{@img}` tags can now be customized using
+    the --img and --link command line options to supply HTML templates.
+  * Links to source code are no more simply links to line numbers.
+    Instead the source code files will contain ID-s like `MyClass-cfg-style`.
+  * New tags: `@docauthor`, `@alternateClassName`, `@mixins`.
+    The latter two Ext4 class properties are both detected from code and
+    can also be defined (or overriden) in doc-comments.
+  * Global methods are now placed to separate "global" class.
+    Creation of this can be turned off using `--ignore-global`.
+  * Much improved search feature.
+    Search results are now ordered so that best matches are at the top.
+    No more is there a select-box to match at beginning/middle/end -
+    we automatically search first by exact match, then beginning and
+    finally by middle.  Additionally the search no more lists a lot of
+    duplicates - only the class that defines a method is listed, ignoring
+    all the classes that inherit it.
+  * Support for doc-comments in [SASS](http://sass-lang.com/) .scss files:
+    For now, it's possible to document SASS variables and mixins.
+  * Several bug fixes.
+
 * 0.5 - Search and export
   * Search from the actually generated docs (not through sencha.com)
   * JSON export with --json switch.

data/bin/jsduck

@@ -34,10 +34,28 @@ opts = OptionParser.new do | opts |
     app.template_dir = path
   end
 
-  opts.on('--json', "Produces JSON export instead of HTML documentation.") do |path|
+  opts.on('--json', "Produces JSON export instead of HTML documentation.") do
     app.export = :json
   end
 
+  opts.on('--link=TPL', "HTML template for replacing {@link}.",
+    "Possible placeholders:",
+    "%c - full class name (e.g. 'Ext.Panel')",
+    "%m - class member name (e.g. 'urlEncode')",
+    "%M - class member name, prefixed with hash (e.g. '#urlEncode')",
+    "%a - anchor text for link",
+    "Default value in export: '<a href=\"%c%M\">%a</a>'") do |tpl|
+    app.link_tpl = tpl
+  end
+
+  opts.on('--img=TPL', "HTML template for replacing {@img}.",
+    "Possible placeholders:",
+    "%u - URL from @img tag (e.g. 'some/path.png')",
+    "%a - alt text for image",
+    "Default value in export: '<img src=\"%u\" alt=\"%a\"/>'") do |tpl|
+    app.img_tpl = tpl
+  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.",
@@ -45,6 +63,10 @@ opts = OptionParser.new do | opts |
     app.processes = count.to_i
   end
 
+  opts.on('--ignore-global', "Turns off the creation of global class.") do
+    app.ignore_global = true
+  end
+
   opts.on('-v', '--verbose', "This will fill up your console.") do
     app.verbose = true
   end
@@ -60,7 +82,7 @@ js_files = []
 opts.parse!(ARGV).each do |fname|
   if File.exists?(fname)
     if File.directory?(fname)
-      Dir[fname+"/**/*.js"].each {|f| js_files << f }
+      Dir[fname+"/**/*.{js,css,scss}"].each {|f| js_files << f }
     else
       js_files << fname
     end

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.5'
-  s.date = '2011-03-29'
+  s.version = '0.6'
+  s.date = '2011-04-27'
   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/aggregator.rb

@@ -1,5 +1,3 @@
-require 'jsduck/merger'
-
 module JsDuck
 
   # Combines JavaScript Parser, DocParser and Merger.
@@ -10,44 +8,17 @@ module JsDuck
       @classes = {}
       @orphans = []
       @current_class = nil
-      @merger = Merger.new
     end
 
     # Combines chunk of parsed JavaScript together with previously
     # added chunks.  The resulting documentation is accumulated inside
     # this class and can be later accessed through #result method.
     #
-    # - input  parse result from JsDuck::Parser
-    # - filename  name of the JS file where it came from
-    # - html_filename  name of the HTML file where the source was saved.
+    # - file  SoureFile class instance
     #
-    def aggregate(input, filename="", html_filename="")
+    def aggregate(file)
       @current_class = nil
-      input.each do |docset|
-        doc = @merger.merge(docset[:comment], docset[:code])
-
-        add_source_data(doc, {
-          :filename => filename,
-          :html_filename => html_filename,
-          :linenr => docset[:linenr],
-        })
-
-        register(doc)
-      end
-    end
-
-    # Links doc-object to source code where it came from.
-    def add_source_data(doc, src)
-      doc[:href] = src[:html_filename] + "#line-" + src[:linenr].to_s
-      doc[:filename] = src[:filename]
-      doc[:linenr] = src[:linenr]
-      # class-level doc-comment can contain constructor and config
-      # options, link those to the same location in source.
-      if doc[:tagname] == :class
-        doc[:cfg].each {|cfg| add_source_data(cfg, src) }
-        doc[:method].each {|method| add_source_data(method, src) }
-      end
-      doc
+      file.each {|doc| register(doc) }
     end
 
     # Registers documentation node either as class or as member of
@@ -80,6 +51,9 @@ module JsDuck
       [:extends, :xtype, :singleton, :private].each do |tag|
         old[tag] = old[tag] || new[tag]
       end
+      [:mixins, :alternateClassNames].each do |tag|
+        old[tag] = old[tag] + new[tag]
+      end
       old[:doc] = old[:doc].length > 0 ? old[:doc] : new[:doc]
       old[:cfg] = old[:cfg] + new[:cfg]
     end
@@ -121,6 +95,53 @@ module JsDuck
       end
     end
 
+    # Creates classes for orphans that have :member property defined,
+    # and then inserts orphans to these classes.
+    def classify_orphans
+      @orphans.each do |orph|
+        if orph[:member]
+          class_name = orph[:member]
+          if !@classes[class_name]
+            add_empty_class(class_name)
+          end
+          add_member(orph)
+          @orphans.delete(orph)
+        end
+      end
+    end
+
+    # Creates class with name "global" and inserts all the remaining
+    # orphans into it (but only if there are any orphans).
+    def create_global_class
+      return if @orphans.length == 0
+
+      add_empty_class("global", "Global variables and functions.")
+      @orphans.each do |orph|
+        orph[:member] = "global"
+        add_member(orph)
+      end
+      @orphans = []
+    end
+
+    def add_empty_class(name, doc = "")
+      add_class({
+        :tagname => :class,
+        :name => name,
+        :doc => doc,
+        :mixins => [],
+        :alternateClassNames => [],
+        :cfg => [],
+        :property => [],
+        :method => [],
+        :event => [],
+        :css_var => [],
+        :css_mixin => [],
+        :filename => "",
+        :html_filename => "",
+        :linenr => 0,
+      })
+    end
+
     def result
       @documentation + @orphans
     end

data/lib/jsduck/app.rb

@@ -1,7 +1,7 @@
 require 'rubygems'
-require 'jsduck/parser'
 require 'jsduck/aggregator'
-require 'jsduck/source_formatter'
+require 'jsduck/source_file'
+require 'jsduck/source_writer'
 require 'jsduck/class'
 require 'jsduck/tree'
 require 'jsduck/tree_icons'
@@ -24,6 +24,9 @@ module JsDuck
     attr_accessor :input_files
     attr_accessor :verbose
     attr_accessor :export
+    attr_accessor :link_tpl
+    attr_accessor :img_tpl
+    attr_accessor :ignore_global
 
     def initialize
       @output_dir = nil
@@ -31,6 +34,9 @@ module JsDuck
       @input_files = []
       @verbose = false
       @export = nil
+      @link_tpl = nil
+      @img_tpl = nil
+      @ignore_global = false
       @timer = Timer.new
       @parallel = ParallelWrap.new
     end
@@ -43,21 +49,21 @@ module JsDuck
 
     # Call this after input parameters set
     def run
-      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) }
       relations = @timer.time(:aggregating) { filter_classes(result) }
+      warn_globals(relations)
+      warn_unnamed(relations)
 
+      clear_dir(@output_dir)
       if @export == :json
+        FileUtils.mkdir(@output_dir)
+        init_output_dirs(@output_dir)
+        @timer.time(:generating) { write_src(@output_dir+"/source", parsed_files) }
         @timer.time(:generating) { write_json(@output_dir+"/output", relations) }
       else
+        copy_template(@template_dir, @output_dir)
+        @timer.time(:generating) { write_src(@output_dir+"/source", parsed_files) }
         @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) }
@@ -68,15 +74,9 @@ module JsDuck
 
     # Parses the files in parallel using as many processes as available CPU-s
     def parallel_parse(filenames)
-      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)
-        {
-          :filename => fname,
-          :html_filename => File.basename(src.write(code, fname)),
-          :data => Parser.new(code).parse,
-        }
+        SourceFile.new(IO.read(fname), fname)
       end
     end
 
@@ -84,9 +84,11 @@ module JsDuck
     def aggregate(parsed_files)
       agr = Aggregator.new
       parsed_files.each do |file|
-        puts "Aggregating #{file[:filename]} ..." if @verbose
-        agr.aggregate(file[:data], file[:filename], file[:html_filename])
+        puts "Aggregating #{file.filename} ..." if @verbose
+        agr.aggregate(file)
       end
+      agr.classify_orphans
+      agr.create_global_class unless @ignore_global
       agr.result
     end
 
@@ -108,6 +110,35 @@ module JsDuck
       Relations.new(classes)
     end
 
+    # print warning for each global member
+    def warn_globals(relations)
+      global = relations["global"]
+      return unless global
+      [:cfg, :property, :method, :event].each do |type|
+        global.members(type).each do |member|
+          name = member[:name]
+          file = member[:filename]
+          line = member[:linenr]
+          puts "Warning: Global #{type}: #{name} in #{file} line #{line}"
+        end
+      end
+    end
+
+    # print warning for each member with no name
+    def warn_unnamed(relations)
+      relations.each do |cls|
+        [:cfg, :property, :method, :event].each do |type|
+          cls[type].each do |member|
+            if !member[:name] || member[:name] == ""
+              file = member[:filename]
+              line = member[:linenr]
+              puts "Warning: Unnamed #{type} in #{file} line #{line}"
+            end
+          end
+        end
+      end
+    end
+
     # Given all classes, generates namespace tree and writes it
     # in JSON form into a file.
     def write_tree(filename, relations)
@@ -133,14 +164,20 @@ module JsDuck
       @parallel.each(relations.classes) do |cls|
         filename = path + "/" + cls[:name] + ".html"
         puts "Writing to #{filename} ..." if @verbose
-        html = Page.new(cls, relations, cache).to_html
-        File.open(filename, 'w') {|f| f.write(html) }
+        page = Page.new(cls, relations, cache)
+        page.link_tpl = @link_tpl if @link_tpl
+        page.img_tpl = @img_tpl if @img_tpl
+        File.open(filename, 'w') {|f| f.write(page.to_html) }
       end
     end
 
     # Writes JSON export file for each class
     def write_json(path, relations)
-      exporter = Exporter.new(relations)
+      formatter = DocFormatter.new
+      formatter.link_tpl = @link_tpl if @link_tpl
+      formatter.img_tpl = @img_tpl if @img_tpl
+      formatter.relations = relations
+      exporter = Exporter.new(relations, formatter)
       @parallel.each(relations.classes) do |cls|
         filename = path + "/" + cls[:name] + ".json"
         puts "Writing to #{filename} ..." if @verbose
@@ -150,6 +187,18 @@ module JsDuck
       end
     end
 
+    # Writes formatted HTML source code for each input file
+    def write_src(path, parsed_files)
+      src = SourceWriter.new(path, @export ? nil : :page)
+      # Can't be done in parallel, because file.html_filename= method
+      # updates all the doc-objects related to the file
+      parsed_files.each do |file|
+        html_filename = src.write(file.to_html, file.filename)
+        puts "Writing to #{html_filename} ..." if @verbose
+        file.html_filename = File.basename(html_filename)
+      end
+    end
+
     def copy_template(template_dir, dir)
       puts "Copying template files to #{dir}..." if @verbose
       FileUtils.cp_r(template_dir, dir)

data/lib/jsduck/cfg_table.rb

@@ -3,8 +3,8 @@ require 'jsduck/table'
 module JsDuck
 
   class CfgTable < Table
-    def initialize(cls, cache={})
-      super(cls, cache)
+    def initialize(cls, formatter, cache={})
+      super(cls, formatter, cache)
       @type = :cfg
       @id = @cls.full_name + "-configs"
       @title = "Config Options"

data/lib/jsduck/class.rb

@@ -36,6 +36,11 @@ module JsDuck
       @doc[:mixins] ? @doc[:mixins].collect {|classname| lookup(classname) }.compact : []
     end
 
+    # Returns all mixins this class and its parent classes
+    def all_mixins
+      mixins + (parent ? parent.all_mixins : [])
+    end
+
     # Looks up class object by name
     # When not found, prints warning message.
     def lookup(classname)

data/lib/jsduck/css_parser.rb

@@ -0,0 +1,75 @@
+require 'jsduck/lexer'
+require 'jsduck/doc_parser'
+
+module JsDuck
+
+  class CssParser
+    def initialize(input)
+      @lex = Lexer.new(input)
+      @doc_parser = DocParser.new(:css)
+      @docs = []
+    end
+
+    # Parses the whole CSS block and returns same kind of structure
+    # that JavaScript parser does.
+    def parse
+      while !@lex.empty? do
+        if look(:doc_comment)
+          comment = @lex.next(true)
+          @docs << {
+            :comment => @doc_parser.parse(comment[:value]),
+            :linenr => comment[:linenr],
+            :code => code_block
+          }
+        else
+          @lex.next
+        end
+      end
+      @docs
+    end
+
+    # <code-block> := <mixin> | <nop>
+    def code_block
+      if look("@", "mixin")
+        mixin
+      else
+        {:type => :nop}
+      end
+    end
+
+    # <mixin> := "@mixin" <css-ident>
+    def mixin
+      match("@", "mixin")
+      return {
+        :type => :css_mixin,
+        :name => look(:ident) ? css_ident : nil,
+      }
+    end
+
+    # <css-ident> := <ident>  [ "-" <ident> ]*
+    def css_ident
+      chain = [match(:ident)]
+      while look("-", :ident) do
+        chain << match("-", :ident)
+      end
+      return chain.join("-")
+    end
+
+    # Matches all arguments, returns the value of last match
+    # When the whole sequence doesn't match, throws exception
+    def match(*args)
+      if look(*args)
+        last = nil
+        args.length.times { last = @lex.next }
+        last
+      else
+        throw "Expected: " + args.join(", ")
+      end
+    end
+
+    def look(*args)
+      @lex.look(*args)
+    end
+  end
+
+end