jsduck 4.0.1 → 4.1.1

data/jsduck.gemspec

@@ -2,8 +2,8 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = ">= 1.3.5"
 
   s.name = 'jsduck'
-  s.version = '4.0.1'
-  s.date = '2012-08-21'
+  s.version = '4.1.1'
+  s.date = '2012-09-14'
   s.summary = "Simple JavaScript Duckumentation generator"
   s.description = "Documentation generator for Sencha JS frameworks"
   s.homepage = "https://github.com/senchalabs/jsduck"
@@ -12,7 +12,7 @@ Gem::Specification.new do |s|
   s.rubyforge_project = s.name
 
   s.files = `git ls-files`.split("\n").find_all do |file|
-    file !~ /spec.rb$/ && file !~ /benchmark/ && file !~ /template\// && file !~ /opt\//
+    file !~ /spec.rb$/ && file !~ /benchmark/ && file !~ /template\// && file !~ /opt\// && file !~ /comments\//
   end
   # Add files not in git
   s.files += Dir['template-min/**/*']

data/lib/jsduck/accessors.rb

@@ -9,37 +9,39 @@ 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].find_all {|m| m[:tagname] == :cfg && m[:accessor] }
 
       # Build lookup tables of method and event names
-      methods = build_lookup_table(cls[:members][:method])
-      events = build_lookup_table(cls[:members][:event])
+      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
         get = create_getter(cfg)
         if !methods[get[:name]]
-          cls[:members][:method] << get
+          cls[:members] << get
         end
         # add setter if no method with same name exists
         set = create_setter(cfg)
         if !methods[set[:name]]
-          cls[:members][:method] << set
+          cls[:members] << 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
+            cls[:members] << ev
           end
         end
       end
     end
 
-    def build_lookup_table(members)
+    def build_lookup_table(members, tagname)
       map = {}
-      members.each {|m| map[m[:name]] = m }
+      members.each do |m|
+        map[m[:name]] = m if m[:tagname] == tagname
+      end
       map
     end
 

data/lib/jsduck/aggregator.rb

@@ -81,7 +81,7 @@ module JsDuck
     def warn_alt_name(cls)
       file = cls[:files][0][:filename]
       line = cls[:files][0][:linenr]
-      Logger.instance.warn(:alt_name, "Name #{cls[:name]} used as both classname and alternate classname", file, line)
+      Logger.warn(:alt_name, "Name #{cls[:name]} used as both classname and alternate classname", file, line)
     end
 
     # Merges new class-doc into old one.
@@ -106,8 +106,7 @@ module JsDuck
       end
       old[:doc] = old[:doc].length > 0 ? old[:doc] : new[:doc]
       # Additionally the doc-comment can contain configs and constructor
-      old[:members][:cfg] += new[:members][:cfg]
-      old[:members][:method] += new[:members][:method]
+      old[:members] += new[:members]
     end
 
     # Tries to place members into classes where they belong.
@@ -138,7 +137,7 @@ module JsDuck
     end
 
     def add_to_class(cls, member)
-      cls[member[:meta][:static] ? :statics : :members][member[:tagname]] << member
+      cls[:members] << member
     end
 
     def add_orphan(node)
@@ -188,8 +187,7 @@ module JsDuck
         :doc => doc,
         :mixins => [],
         :alternateClassNames => [],
-        :members => Class.default_members_hash,
-        :statics => Class.default_members_hash,
+        :members => [],
         :aliases => {},
         :meta => {},
         :files => [{:filename => "", :linenr => 0, :href => ""}],
@@ -215,7 +213,9 @@ module JsDuck
         :doc => "The options object passed to {@link Ext.util.Observable#addListener}."
       }
       @classes.each_value do |cls|
-        cls[:members][:event].each {|e| e[:params] << options }
+        cls[:members].each do |m|
+          m[:params] << options if m[:tagname] == :event
+        end
       end
     end
 

data/lib/jsduck/app.rb

@@ -1,31 +1,8 @@
-require 'rubygems'
-require 'jsduck/aggregator'
-require 'jsduck/source_file'
-require 'jsduck/doc_formatter'
-require 'jsduck/class_formatter'
-require 'jsduck/class'
-require 'jsduck/relations'
-require 'jsduck/inherit_doc'
-require 'jsduck/parallel_wrap'
-require 'jsduck/logger'
+require 'jsduck/batch_parser'
 require 'jsduck/assets'
-require 'jsduck/json_duck'
-require 'jsduck/io'
-require 'jsduck/importer'
-require 'jsduck/lint'
-require 'jsduck/template_dir'
-require 'jsduck/class_writer'
-require 'jsduck/source_writer'
-require 'jsduck/app_data'
-require 'jsduck/index_html'
-require 'jsduck/api_exporter'
-require 'jsduck/full_exporter'
-require 'jsduck/app_exporter'
-require 'jsduck/examples_exporter'
-require 'jsduck/inline_examples'
-require 'jsduck/guide_writer'
-require 'jsduck/stdout'
-require 'fileutils'
+require 'jsduck/meta_tag_registry'
+require 'jsduck/export_writer'
+require 'jsduck/web_writer'
 
 module JsDuck
 
@@ -34,159 +11,42 @@ module JsDuck
     # Initializes app with JsDuck::Options object
     def initialize(opts)
       @opts = opts
-      # Sets the nr of parallel processes to use.
-      # Set to 0 to disable parallelization completely.
-      ParallelWrap.in_processes = @opts.processes
-      # Turn JSON pretty-printing on/off
-      JsonDuck.pretty = @opts.pretty_json
     end
 
-    # Call this after input parameters set
+    # Main App logic.
     def run
-      parsed_files = parallel_parse(@opts.input_files)
-      result = aggregate(parsed_files)
-      @relations = filter_classes(result)
-      InheritDoc.new(@relations).resolve_all
-      Importer.import(@opts.imports, @relations, @opts.new_since)
-      Lint.new(@relations).run
+      parse
 
-      # Initialize guides, videos, examples, ...
-      @assets = Assets.new(@relations, @opts)
-
-      # Give access to assets from all meta-tags
-      MetaTagRegistry.instance.assets = @assets
+      init_assets
 
       if @opts.export
-        format_classes
-        FileUtils.rm_rf(@opts.output_dir) unless @opts.output_dir == :stdout
-        exporters = {
-          :full => FullExporter,
-          :api => ApiExporter,
-          :examples => ExamplesExporter,
-        }
-        cw = ClassWriter.new(exporters[@opts.export], @relations, @opts)
-        cw.write(@opts.output_dir, ".json")
-        if @opts.export == :examples
-          gw = GuideWriter.new(exporters[@opts.export], @assets.guides, @opts)
-          gw.write(@opts.output_dir, ".json")
-        end
-        Stdout.instance.flush
+        generate_export
       else
-        FileUtils.rm_rf(@opts.output_dir)
-        TemplateDir.new(@opts).write
-
-        IndexHtml.new(@assets, @opts).write
-
-        AppData.new(@relations, @assets, @opts).write(@opts.output_dir+"/data.js")
-
-        # class-formatting is done in parallel which breaks the links
-        # between source files and classes. Therefore it MUST to be done
-        # after writing sources which needs the links to work.
-        if @opts.source
-          source_writer = SourceWriter.new(parsed_files)
-          source_writer.write(@opts.output_dir + "/source")
-        end
-        format_classes
-
-        if @opts.tests
-          examples = InlineExamples.new
-          examples.add_classes(@relations)
-          examples.add_guides(@assets.guides)
-          examples.write(@opts.output_dir+"/inline-examples.js")
-        end
-
-        cw = ClassWriter.new(AppExporter, @relations, @opts)
-        cw.write(@opts.output_dir+"/output", ".js")
-
-        @assets.write
+        generate_web_page
       end
     end
 
-    # Parses the files in parallel using as many processes as available CPU-s
-    def parallel_parse(filenames)
-      ParallelWrap.map(filenames) do |fname|
-        Logger.instance.log("Parsing", fname)
-        begin
-          SourceFile.new(JsDuck::IO.read(fname), fname, @opts)
-        rescue
-          Logger.instance.fatal_backtrace("Error while parsing #{fname}", $!)
-          exit(1)
-        end
-      end
-    end
+    private
 
-    # Aggregates parsing results sequencially
-    def aggregate(parsed_files)
-      agr = Aggregator.new
-      parsed_files.each do |file|
-        Logger.instance.log("Aggregating", file.filename)
-        agr.aggregate(file)
-      end
-      agr.classify_orphans
-      agr.create_global_class
-      agr.remove_ignored_classes
-      agr.create_accessors
-      if @opts.ext4_events == true || (@opts.ext4_events == nil && agr.ext4?)
-        agr.append_ext4_event_options
-      end
-      agr.process_enums
-      # Ignore override classes after applying them to actual classes
-      @opts.external_classes += agr.process_overrides.map {|o| o[:name] }
-      agr.result
+    def parse
+      @batch_parser = BatchParser.new(@opts)
+      @relations = @batch_parser.run
     end
 
-    # Turns all aggregated data into Class objects.
-    # Depending on --ignore-global either keeps or discards the global class.
-    # Warnings for global members are printed regardless of that setting,
-    # but of course can be turned off using --warnings=-global
-    def filter_classes(docs)
-      classes = []
-      docs.each do |d|
-        cls = Class.new(d)
-        if d[:name] != "global"
-          classes << cls
-        else
-          # add global class only if --ignore-global not specified
-          classes << cls unless @opts.ignore_global
+    def init_assets
+      # Initialize guides, videos, examples, ...
+      @assets = Assets.new(@relations, @opts)
 
-          # Print warning for each global member
-          cls.all_local_members.each do |m|
-            type = m[:tagname].to_s
-            name = m[:name]
-            file = m[:files][0]
-            Logger.instance.warn(:global, "Global #{type}: #{name}", file[:filename], file[:linenr])
-          end
-        end
-      end
-      Relations.new(classes, @opts.external_classes)
+      # Give access to assets from all meta-tags
+      MetaTagRegistry.instance.assets = @assets
     end
 
-    # Formats each class
-    def format_classes
-      doc_formatter = DocFormatter.new(@relations, @opts)
-      doc_formatter.img_path = "images"
-      class_formatter = ClassFormatter.new(@relations, doc_formatter)
-      # Don't format types when exporting
-      class_formatter.include_types = !@opts.export
-      # Format all doc-objects in parallel
-      formatted_classes = ParallelWrap.map(@relations.classes) do |cls|
-        files = cls[:files].map {|f| f[:filename] }.join(" ")
-        Logger.instance.log("Markdown formatting #{cls[:name]}", files)
-        begin
-          {
-            :doc => class_formatter.format(cls.internal_doc),
-            :images => doc_formatter.images
-          }
-        rescue
-          Logger.instance.fatal_backtrace("Error while formatting #{cls[:name]} #{files}", $!)
-          exit(1)
-        end
-      end
-      # Then merge the data back to classes sequentially
-      formatted_classes.each do |cls|
-        @relations[cls[:doc][:name]].internal_doc = cls[:doc]
-        cls[:images].each {|img| @assets.images.add(img) }
-      end
+    def generate_export
+      ExportWriter.new(@relations, @assets, @opts).write
+    end
+
+    def generate_web_page
+      WebWriter.new(@relations, @assets, @batch_parser.parsed_files, @opts).write
     end
 
   end

data/lib/jsduck/app_data.rb

@@ -1,7 +1,6 @@
-require 'jsduck/json_duck'
+require 'jsduck/util/json'
 require 'jsduck/icons'
 require 'jsduck/search_data'
-require 'jsduck/stats'
 require 'jsduck/meta_tag_registry'
 
 module JsDuck
@@ -16,14 +15,13 @@ module JsDuck
 
     # Writes classes, guides, videos, and search data to one big .js file
     def write(filename)
-      js = "Docs = " + JsonDuck.generate({
+      js = "Docs = " + Util::Json.generate({
         :data => {
           :classes => Icons.new.create(@relations.classes),
           :guides => @assets.guides.to_array,
           :videos => @assets.videos.to_array,
           :examples => @assets.examples.to_array,
           :search => SearchData.new.create(@relations.classes, @assets),
-          :stats => @opts.stats ? Stats.new.create(@relations.classes) : [],
           :tests => @opts.tests,
           :signatures => MetaTagRegistry.instance.signatures,
           :localStorageDb => @opts.local_storage_db,

data/lib/jsduck/assets.rb

@@ -26,12 +26,15 @@ module JsDuck
       @relations = relations
       @opts = opts
 
+      doc_formatter = DocFormatter.new(@opts)
+      doc_formatter.relations = @relations
+
       @images = Images.new(@opts.images)
       @welcome = Welcome.create(@opts.welcome)
-      @guides = Guides.create(@opts.guides, DocFormatter.new(@relations, @opts), @opts)
+      @guides = Guides.create(@opts.guides, doc_formatter, @opts)
       @videos = Videos.create(@opts.videos)
       @examples = Examples.create(@opts.examples, @opts)
-      @categories = Categories.create(@opts.categories_path, DocFormatter.new(@relations, @opts), @relations)
+      @categories = Categories.create(@opts.categories_path, doc_formatter, @relations)
     end
 
     # Writes out the assets that can be written out separately:

data/lib/jsduck/ast.rb

@@ -1,5 +1,6 @@
 require "jsduck/serializer"
 require "jsduck/evaluator"
+require "jsduck/function_ast"
 
 module JsDuck
 
@@ -224,7 +225,6 @@ module JsDuck
       cls[:mixins] = []
       cls[:aliases] = []
       cls[:members] = []
-      cls[:statics] = []
       cls[:code_type] = :ext_define
 
       each_pair_in_object_expression(ast["arguments"][1]) do |key, value, pair|
@@ -254,9 +254,9 @@ module JsDuck
         when "eventedConfig"
           cls[:members] += make_configs(value, {:accessor => true, :evented => true})
         when "statics"
-          cls[:statics] += make_statics(value)
+          cls[:members] += make_statics(value)
         when "inheritableStatics"
-          cls[:statics] += make_statics(value, {:inheritable => true})
+          cls[:members] += make_statics(value, {:inheritable => true})
         else
           detect_method_or_property(cls, key, value, pair)
         end
@@ -393,7 +393,8 @@ module JsDuck
       return {
         :tagname => :method,
         :name => name,
-        :params => make_params(ast)
+        :params => make_params(ast),
+        :chainable => chainable?(ast) && name != "constructor",
       }
     end
 
@@ -405,6 +406,10 @@ module JsDuck
       end
     end
 
+    def chainable?(ast)
+      FunctionAst.chainable?(ast)
+    end
+
     def make_property(name=nil, ast=nil, tagname=:property)
       return {
         :tagname => tagname,

data/lib/jsduck/batch_formatter.rb

@@ -0,0 +1,54 @@
+require 'jsduck/util/parallel'
+require 'jsduck/class_formatter'
+require 'jsduck/doc_formatter'
+require 'jsduck/logger'
+
+module JsDuck
+
+  # Performs the formatting of the doc-object of all classes.
+  class BatchFormatter
+
+    # Formats all classes.
+    # Also registers found images in assets.
+    def self.format_all!(relations, assets, opts)
+      # Format all doc-objects in parallel
+      formatted_classes = Util::Parallel.map(relations.classes) do |cls|
+
+        files = cls[:files].map {|f| f[:filename] }.join(" ")
+        Logger.log("Markdown formatting #{cls[:name]}", files)
+
+        formatter = create_class_formatter(relations, opts)
+        begin
+          {
+            :doc => formatter.format(cls.internal_doc),
+            :images => formatter.images
+          }
+        rescue
+          Logger.fatal_backtrace("Error while formatting #{cls[:name]} #{files}", $!)
+          exit(1)
+        end
+      end
+
+      # Then merge the data back to classes sequentially
+      formatted_classes.each do |cls|
+        relations[cls[:doc][:name]].internal_doc = cls[:doc]
+        cls[:images].each {|img| assets.images.add(img) }
+      end
+    end
+
+    # Factory method to create new ClassFormatter instances.
+    def self.create_class_formatter(relations, opts)
+      doc_formatter = DocFormatter.new(opts)
+      doc_formatter.relations = relations
+      doc_formatter.img_path = "images"
+
+      class_formatter = ClassFormatter.new(relations, doc_formatter)
+      # Don't format types when exporting
+      class_formatter.include_types = !opts.export
+
+      class_formatter
+    end
+
+  end
+
+end