jsduck 3.0.pre2 → 3.0.pre3

data/bin/stats

@@ -0,0 +1,92 @@
+#!/usr/bin/env ruby
+# Print stats for JSON export
+
+# For running when gem not installed
+$:.unshift File.dirname(File.dirname(__FILE__)) + "/lib"
+
+require "rubygems"
+require "jsduck/json_duck"
+
+def read_all_classes(dir)
+  classes = []
+  Dir[dir+"/*.json"].each do |filename|
+    print "."
+    STDOUT.flush
+    classes << JsDuck::JsonDuck.read(filename)
+  end
+  puts "OK"
+  classes
+end
+
+def count_members(classes, group, type)
+  classes.map do |c|
+    c[group][type].find_all {|m| m["owner"] == c["name"] }
+  end.flatten.length
+end
+
+# Strips HTML and counts words in text
+def wc(string)
+  string.gsub(/<\/?[^>]*>/, "").scan(/\w+/).size
+end
+
+def property_wc(property)
+  cnt = wc(property["doc"])
+  (property["properties"] || []).each {|p| cnt += property_wc(p) }
+  cnt
+end
+
+def class_wc(cls)
+  cnt = wc(cls["doc"])
+  ["members", "statics"].each do |group|
+    cls[group].each_value do |members|
+      members.find_all {|m| m["owner"] == cls["name"] }.each do |m|
+        cnt += wc(m["doc"])
+        (m["params"] || []).each {|p| cnt += property_wc(p) }
+        (m["properties"] || []).each {|p| cnt += property_wc(p) }
+        cnt += wc(m["return"]["doc"]) if m["return"]
+      end
+    end
+  end
+  cnt
+end
+
+classes = read_all_classes(ARGV[0])
+
+puts "%d classes in total" % classes.length
+puts "%d public classes" % classes.find_all {|c| !c["private"] }.length
+puts "%d private classes" % classes.find_all {|c| c["private"] }.length
+puts
+
+mem = count_members(classes, "members", "cfg")
+sta = count_members(classes, "statics", "cfg")
+puts "%d public cfgs" % (mem+sta)
+puts "    %d instance" % mem
+puts "    %d static" % sta
+
+mem = count_members(classes, "members", "property")
+sta = count_members(classes, "statics", "property")
+puts "%d public properties" % (mem+sta)
+puts "    %d instance" % mem
+puts "    %d static" % sta
+
+mem = count_members(classes, "members", "method")
+sta = count_members(classes, "statics", "method")
+puts "%d public methods" % (mem+sta)
+puts "    %d instance" % mem
+puts "    %d static" % sta
+
+mem = count_members(classes, "members", "event")
+sta = count_members(classes, "statics", "event")
+puts "%d public events" % (mem+sta)
+puts "    %d instance" % mem
+puts "    %d static" % sta
+
+puts
+puts "Word counts"
+puts "-----------"
+classes.map {|cls| [cls, class_wc(cls)] }.sort {|a,b| a[1] <=> b[1] }.each do |pair|
+  puts "%d %s" % [pair[1], pair[0]["name"]]
+end
+
+puts
+puts "%d total words in documentation" % classes.map {|cls| class_wc(cls) }.inject(0) {|a,b| a+b }

data/jsduck.gemspec

@@ -2,10 +2,10 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = ">= 1.3.7"
 
   s.name = 'jsduck'
-  s.version = '3.0.pre2'
-  s.date = '2011-09-20'
+  s.version = '3.0.pre3'
+  s.date = '2011-10-17'
   s.summary = "Simple JavaScript Duckumentation generator"
-  s.description = "Documentation generator for ExtJS 4"
+  s.description = "Documentation generator for Sencha JS frameworks"
   s.homepage = "https://github.com/senchalabs/jsduck"
   s.authors = ["Rene Saarsoo", "Nick Poulden"]
   s.email = "rene.saarsoo@sencha.com"

data/lib/jsduck/accessors.rb

@@ -9,13 +9,11 @@ module JsDuck
     # not added.
     def create(cls)
       # Grab all configs tagged as @accessor
-      accessors = cls[:members][:cfg].find_all {|cfg| cfg[:accessor] }
+      accessors = cls[:members][:cfg].find_all {|cfg| cfg[:accessor] && !cfg[:private] }
 
-      # Build lookup table of method names
-      methods = {}
-      cls[:members][:method].each do |m|
-        methods[m[:name]] = m;
-      end
+      # Build lookup tables of method and event names
+      methods = build_lookup_table(cls[:members][:method])
+      events = build_lookup_table(cls[:members][:event])
 
       accessors.each do |cfg|
         # add getter if no method with same name exists
@@ -28,13 +26,28 @@ module JsDuck
         if !methods[set[:name]]
           cls[:members][:method] << set
         end
+        # for evented accessors
+        if cfg[:evented]
+          # add event if no event with same name exists
+          ev = create_event(cfg)
+          if !events[ev[:name]]
+            cls[:members][:event] << ev
+          end
+        end
       end
     end
 
+    def build_lookup_table(members)
+      map = {}
+      members.each {|m| map[m[:name]] = m }
+      map
+    end
+
     def create_getter(cfg)
+      name = "get" + upcase_first(cfg[:name])
       return {
         :tagname => :method,
-        :name => "get" + upcase_first(cfg[:name]),
+        :name => name,
         :doc => "Returns the value of {@link #cfg-#{cfg[:name]}}.",
         :params => [],
         :return => {
@@ -42,13 +55,17 @@ module JsDuck
           :doc => "",
         },
         :owner => cfg[:owner],
+        :files => cfg[:files],
+        :id => "method-" + name,
+        :deprecated => cfg[:deprecated],
       }
     end
 
     def create_setter(cfg)
+      name = "set" + upcase_first(cfg[:name]);
       return {
         :tagname => :method,
-        :name => "set" + upcase_first(cfg[:name]),
+        :name => name,
         :doc => "Sets the value of {@link #cfg-#{cfg[:name]}}.",
         :params => [{
             :type => cfg[:type],
@@ -60,6 +77,45 @@ module JsDuck
           :doc => "",
         },
         :owner => cfg[:owner],
+        :files => cfg[:files],
+        :id => "method-" + name,
+        :deprecated => cfg[:deprecated],
+      }
+    end
+
+    def create_event(cfg)
+      name = cfg[:name].downcase + "change"
+      setter_name = "set" + upcase_first(cfg[:name]);
+      return {
+        :tagname => :event,
+        :name => name,
+        :doc =>
+          "Fires when the {@link ##{cfg[:id]}} configuration is changed by {@link #method-#{setter_name}}." +
+          "\n\n" +
+          "Note that this event is fired *before* the value of {@link ##{cfg[:id]}} has been updated, " +
+          "and that you can return false from any listener to the #{name} event " +
+          "to cancel the change.",
+        :params => [
+          {
+            :name => "this",
+            :type => cfg[:owner],
+            :doc => "The #{cfg[:owner]} instance."
+          },
+          {
+            :name => "value",
+            :type => cfg[:type],
+            :doc => "The new value being set."
+          },
+          {
+            :name => "oldValue",
+            :type => cfg[:type],
+            :doc => "The existing value."
+          },
+        ],
+        :owner => cfg[:owner],
+        :files => cfg[:files],
+        :id => "event-" + name,
+        :deprecated => cfg[:deprecated],
       }
     end
 

data/lib/jsduck/aggregator.rb

@@ -51,14 +51,19 @@ module JsDuck
 
     # Merges new class-doc into old one.
     def merge_classes(old, new)
+      # Merge booleans
       [:extends, :singleton, :private, :protected].each do |tag|
         old[tag] = old[tag] || new[tag]
       end
-      [:mixins, :alternateClassNames].each do |tag|
+      # Merge arrays
+      [:mixins, :alternateClassNames, :files].each do |tag|
         old[tag] = old[tag] + new[tag]
       end
-      new[:xtypes].each_pair do |key, xtypes|
-        old[:xtypes][key] = (old[:xtypes][key] || []) + xtypes
+      # Merge hashes of arrays
+      [:xtypes, :meta].each do |tag|
+        new[tag].each_pair do |key, contents|
+          old[tag][key] = (old[tag][key] || []) + contents
+        end
       end
       old[:doc] = old[:doc].length > 0 ? old[:doc] : new[:doc]
       # Additionally the doc-comment can contain configs and constructor
@@ -144,9 +149,8 @@ module JsDuck
         :alternateClassNames => [],
         :members => Class.default_members_hash,
         :statics => Class.default_members_hash,
-        :filename => "",
-        :html_filename => "",
-        :linenr => 0,
+        :meta => {},
+        :files => [{:filename => "", :linenr => 0}],
       })
     end
 

data/lib/jsduck/aliases.rb

@@ -28,16 +28,17 @@ module JsDuck
     # Given aliased member, finds the original member.
     # If the original also happens to be an alias, continue recursively.
     def find_original(al)
+      context = al[:files][0]
       al_def = al[:alias]
 
       orig = @relations[al_def[:cls]]
       unless orig
-        Logger.instance.warn("Class #{al_def[:cls]} not found in #{al[:filename]} line #{al[:linenr]}")
+        Logger.instance.warn("Class #{al_def[:cls]} not found", context[:filename], context[:linenr])
         return al
       end
       orig = orig.get_member(al_def[:member], al_def[:type] || al[:tagname])
       unless orig
-        Logger.instance.warn("Member #{al_def[:cls]}##{al_def[:member]} not found in #{al[:filename]} line #{al[:linenr]}")
+        Logger.instance.warn("Member #{al_def[:cls]}##{al_def[:member]} not found", context[:filename], context[:linenr])
         return al
       end
 

data/lib/jsduck/app.rb

@@ -11,7 +11,6 @@ require 'jsduck/relations'
 require 'jsduck/aliases'
 require 'jsduck/exporter'
 require 'jsduck/renderer'
-require 'jsduck/timer'
 require 'jsduck/parallel_wrap'
 require 'jsduck/logger'
 require 'jsduck/welcome'
@@ -19,6 +18,7 @@ require 'jsduck/guides'
 require 'jsduck/videos'
 require 'jsduck/examples'
 require 'jsduck/categories'
+require 'jsduck/images'
 require 'jsduck/json_duck'
 require 'jsduck/lint'
 require 'fileutils'
@@ -30,7 +30,6 @@ module JsDuck
     # Initializes app with JsDuck::Options object
     def initialize(opts)
       @opts = opts
-      @timer = Timer.new
       # Sets the nr of parallel processes to use.
       # Set to 0 to disable parallelization completely.
       @parallel = ParallelWrap.new(:in_processes => @opts.processes)
@@ -43,47 +42,47 @@ module JsDuck
 
     # Call this after input parameters set
     def run
-      parsed_files = @timer.time(:parsing) { parallel_parse(@opts.input_files) }
-      result = @timer.time(:aggregating) { aggregate(parsed_files) }
-      @relations = @timer.time(:aggregating) { filter_classes(result) }
+      parsed_files = parallel_parse(@opts.input_files)
+      result = aggregate(parsed_files)
+      @relations = filter_classes(result)
       Aliases.new(@relations).resolve_all
       Lint.new(@relations).run
 
+      @images = Images.new(@opts.images)
+
       @welcome = Welcome.new
       if @opts.welcome
-        @timer.time(:parsing) { @welcome.parse(@opts.welcome) }
+        @welcome.parse(@opts.welcome)
       end
 
       @guides = Guides.new(get_doc_formatter)
       if @opts.guides
-        @timer.time(:parsing) { @guides.parse(@opts.guides) }
+        @guides.parse(@opts.guides)
       end
 
       @videos = Videos.new
       if @opts.videos
-        @timer.time(:parsing) { @videos.parse(@opts.videos) }
+        @videos.parse(@opts.videos)
       end
 
       @examples = Examples.new
       if @opts.examples
-        @timer.time(:parsing) { @examples.parse(@opts.examples) }
+        @examples.parse(@opts.examples)
       end
 
       @categories = Categories.new(get_doc_formatter, @relations)
       if @opts.categories_path
-        @timer.time(:parsing) do
-          @categories.parse(@opts.categories_path)
-          @categories.validate
-        end
+        @categories.parse(@opts.categories_path)
+        @categories.validate
       end
 
       clear_output_dir unless @opts.export == :stdout
       if @opts.export == :stdout
-        @timer.time(:generating) { puts JsonDuck.generate(@relations.classes) }
+        puts JsonDuck.generate(@relations.classes)
       elsif @opts.export == :json
         FileUtils.mkdir(@opts.output_dir)
-        @timer.time(:generating) { format_classes }
-        @timer.time(:generating) { write_classes }
+        format_classes
+        write_classes
       else
         if @opts.template_links
           link_template
@@ -96,22 +95,22 @@ module JsDuck
           FileUtils.rm(@opts.output_dir+"/index.php")
           FileUtils.cp(@opts.output_dir+"/template.html", @opts.output_dir+"/index.html")
         end
-        @timer.time(:generating) { write_src(parsed_files) }
-        @timer.time(:generating) { format_classes }
-        @timer.time(:generating) { write_app_data }
-        @timer.time(:generating) { write_classes }
-        @timer.time(:generating) { @guides.write(@opts.output_dir+"/guides") }
-        @timer.time(:generating) { @videos.write(@opts.output_dir+"/videos") }
-        @timer.time(:generating) { @examples.write(@opts.output_dir+"/examples") }
+        write_src(parsed_files)
+        format_classes
+        write_app_data
+        write_classes
+        @guides.write(@opts.output_dir+"/guides")
+        @videos.write(@opts.output_dir+"/videos")
+        @examples.write(@opts.output_dir+"/examples")
+        @images.copy(@opts.output_dir+"/images")
       end
 
-      @timer.report
     end
 
     # Parses the files in parallel using as many processes as available CPU-s
     def parallel_parse(filenames)
       @parallel.map(filenames) do |fname|
-        Logger.instance.log("Parsing #{fname} ...")
+        Logger.instance.log("Parsing", fname)
         SourceFile.new(IO.read(fname), fname, @opts)
       end
     end
@@ -120,7 +119,7 @@ module JsDuck
     def aggregate(parsed_files)
       agr = Aggregator.new
       parsed_files.each do |file|
-        Logger.instance.log("Aggregating #{file.filename} ...")
+        Logger.instance.log("Aggregating", file.filename)
         agr.aggregate(file)
       end
       agr.classify_orphans
@@ -140,9 +139,8 @@ module JsDuck
         else
           type = d[:tagname].to_s
           name = d[:name]
-          file = d[:filename]
-          line = d[:linenr]
-          Logger.instance.warn("Ignoring #{type}: #{name} in #{file} line #{line}")
+          file = d[:files][0]
+          Logger.instance.warn("Ignoring #{type}: #{name}", file[:filename], file[:linenr])
         end
       end
       Relations.new(classes, @opts.external_classes)
@@ -150,16 +148,22 @@ module JsDuck
 
     # Formats each class
     def format_classes
-      formatter = ClassFormatter.new(@relations, get_doc_formatter)
+      doc_formatter = get_doc_formatter
+      doc_formatter.img_path = "images"
+      class_formatter = ClassFormatter.new(@relations, doc_formatter)
       # Don't format types when exporting
-      formatter.include_types = !@opts.export
+      class_formatter.include_types = !@opts.export
       # Format all doc-objects in parallel
-      formatted_docs = @parallel.map(@relations.classes) do |cls|
-        formatter.format(cls.internal_doc)
+      formatted_classes = @parallel.map(@relations.classes) do |cls|
+        {
+          :doc => class_formatter.format(cls.internal_doc),
+          :images => doc_formatter.images
+        }
       end
       # Then merge the data back to classes sequentially
-      formatted_docs.each do |doc|
-        @relations[doc[:name]].internal_doc = doc
+      formatted_classes.each do |cls|
+        @relations[cls[:doc][:name]].internal_doc = cls[:doc]
+        cls[:images].each {|img| @images.add(img) }
       end
     end
 
@@ -178,11 +182,16 @@ module JsDuck
     # Writes JSON export or JsonP file for each class
     def write_classes
       exporter = Exporter.new(@relations)
-      renderer = Renderer.new(@opts)
+      renderer = Renderer.new
+      # Inject formatter to all meta-tags.
+      doc_formatter = get_doc_formatter
+      @opts.meta_tags.each {|tag| tag.formatter = doc_formatter }
+      renderer.meta_tags = @opts.meta_tags
+
       dir = @opts.output_dir + (@opts.export ? "" : "/output")
       @parallel.each(@relations.classes) do |cls|
         filename = dir + "/" + cls[:name] + (@opts.export ? ".json" : ".js")
-        Logger.instance.log("Writing to #{filename} ...")
+        Logger.instance.log("Writing docs", filename)
         data = exporter.export(cls)
         if @opts.export
           JsonDuck.write_json(filename, data)
@@ -201,7 +210,7 @@ module JsDuck
       # updates all the doc-objects related to the file
       parsed_files.each do |file|
         html_filename = src.write(file.to_html, file.filename)
-        Logger.instance.log("Writing to #{html_filename} ...")
+        Logger.instance.log("Writing source", html_filename)
         file.html_filename = File.basename(html_filename)
       end
     end
@@ -212,20 +221,17 @@ module JsDuck
       formatter.link_tpl = @opts.link_tpl if @opts.link_tpl
       formatter.img_tpl = @opts.img_tpl if @opts.img_tpl
       formatter.relations = @relations
-      if @opts.inline_examples_dir
-        formatter.get_example = lambda {|path| IO.read(@opts.inline_examples_dir + "/" + path) }
-      end
       formatter
     end
 
     def copy_template
-      Logger.instance.log("Copying template files to #{@opts.output_dir}...")
+      Logger.instance.log("Copying template files to", @opts.output_dir)
       FileUtils.cp_r(@opts.template_dir, @opts.output_dir)
       init_output_dirs
     end
 
     def link_template
-      Logger.instance.log("Linking template files to #{@opts.output_dir}...")
+      Logger.instance.log("Linking template files to", @opts.output_dir)
       FileUtils.mkdir(@opts.output_dir)
       Dir.glob(@opts.template_dir + "/*").each do |file|
         File.symlink(File.expand_path(file), @opts.output_dir+"/"+File.basename(file))
@@ -252,6 +258,7 @@ module JsDuck
         "{extjs_path}" => @opts.extjs_path,
         "{local_storage_db}" => @opts.local_storage_db,
         "{show_print_button}" => @opts.seo ? "true" : "false",
+        "{touch_examples_ui}" => @opts.touch_examples_ui ? "true" : "false",
         "{welcome}" => @welcome.to_html,
         "{categories}" => @categories.to_html,
         "{guides}" => @guides.to_html,
@@ -271,7 +278,7 @@ module JsDuck
     def write_template(filename, replacements)
       in_file = @opts.template_dir + '/' + filename
       out_file = @opts.output_dir + '/' + filename
-      Logger.instance.log("Creating #{out_file}...")
+      Logger.instance.log("Writing", out_file)
       html = IO.read(in_file)
       html.gsub!(/\{\w+\}/) do |key|
         replacements[key] ? replacements[key] : key

data/lib/jsduck/author_tag.rb

@@ -0,0 +1,11 @@
+require "jsduck/meta_tag"
+
+module JsDuck
+  # Implementation of hidden @author tag
+  class AuthorTag < MetaTag
+    def initialize
+      @name = "author"
+    end
+  end
+end
+

data/lib/jsduck/categories.rb

@@ -13,7 +13,13 @@ module JsDuck
 
     # Parses categories in JSON file
     def parse(path)
-      @categories = JsonDuck.read(path)["categories"]
+      @categories = JsonDuck.read(path)
+
+      # Don't crash if old syntax is used.
+      if @categories.is_a?(Hash) && @categories["categories"]
+        Logger.instance.warn('Update categories file to contain just the array inside {"categories": [...]}')
+        @categories = @categories["categories"]
+      end
 
       # Perform expansion on all class names containing * wildcard
       @categories.each do |cat|
@@ -28,26 +34,26 @@ module JsDuck
     # Expands class name like 'Foo.*' into multiple class names.
     def expand(name)
       re = Regexp.new("^" + name.split(/\*/, -1).map {|part| Regexp.escape(part) }.join('.*') + "$")
-      @relations.to_a.find_all {|cls| re =~ cls[:name] && !cls[:private] }.map {|cls| cls[:name] }.sort
+      classes = @relations.to_a.find_all {|cls| re =~ cls[:name] && !cls[:private] }.map {|cls| cls[:name] }.sort
+      if classes.length == 0
+        Logger.instance.warn("No class found matching a pattern '#{name}' in categories file.")
+      end
+      classes
     end
 
     # Prints warnings for missing classes in categories file
     def validate
+      # Build a map of all classes listed in categories
       listed_classes = {}
-
-      # Check that each class listed in overview file exists
       @categories.each do |cat|
         cat["groups"].each do |group|
           group["classes"].each do |cls_name|
-            unless @relations[cls_name]
-              Logger.instance.warn("Class '#{cls_name}' in category '#{cat['name']}/#{group['name']}' not found")
-            end
             listed_classes[cls_name] = true
           end
         end
       end
 
-      # Check that each existing non-private class is listed in overview file
+      # Check that each existing non-private class is listed
       @relations.each do |cls|
         unless listed_classes[cls[:name]] || cls[:private]
           Logger.instance.warn("Class '#{cls[:name]}' not found in categories file")

data/lib/jsduck/class.rb

@@ -61,7 +61,8 @@ module JsDuck
       if @relations[classname]
         @relations[classname]
       elsif !@relations.ignore?(classname)
-        Logger.instance.warn("Class #{classname} not found in #{@doc[:filename]} line #{@doc[:linenr]}")
+        context = @doc[:files][0]
+        Logger.instance.warn("Class #{classname} not found", context[:filename], context[:linenr])
         nil
       end
     end

data/lib/jsduck/class_formatter.rb

@@ -14,6 +14,7 @@ module JsDuck
       @relations = relations
       @formatter = formatter
       @include_types = true
+      @meta_tags = []
     end
 
     # Runs the formatter on doc object of a class.
@@ -21,7 +22,7 @@ module JsDuck
     def format(cls)
       @cls = cls
       @formatter.class_context = cls[:name]
-      @formatter.doc_context = cls
+      @formatter.doc_context = cls[:files][0]
       cls[:doc] = @formatter.format(cls[:doc]) if cls[:doc]
       cls[:members].each_pair do |type, members|
         cls[:members][type] = members.reject {|m| m[:private] }.map {|m| format_member(m) }
@@ -33,7 +34,7 @@ module JsDuck
     end
 
     def format_member(m)
-      @formatter.doc_context = m
+      @formatter.doc_context = m[:files][0]
       m[:doc] = @formatter.format(m[:doc]) if m[:doc]
       m[:deprecated][:text] = @formatter.format(m[:deprecated][:text]) if m[:deprecated]
       if expandable?(m) || @formatter.too_long?(m[:doc])
@@ -68,9 +69,9 @@ module JsDuck
       else
         context = @formatter.doc_context
         if tp.error == :syntax
-          Logger.instance.warn("Incorrect type syntax #{type} in #{context[:filename]} line #{context[:linenr]}")
+          Logger.instance.warn("Incorrect type syntax #{type}", context[:filename], context[:linenr])
         else
-          Logger.instance.warn("Unknown type #{type} in #{context[:filename]} line #{context[:linenr]}")
+          Logger.instance.warn("Unknown type #{type}", context[:filename], context[:linenr])
         end
         type
       end

data/lib/jsduck/doc_author_tag.rb

@@ -0,0 +1,11 @@
+require "jsduck/meta_tag"
+
+module JsDuck
+  # Implementation of hidden @docauthor tag
+  class DocAuthorTag < MetaTag
+    def initialize
+      @name = "docauthor"
+    end
+  end
+end
+