jsduck 4.10.4 → 5.0.0.beta01

data/.travis.yml

@@ -6,7 +6,6 @@ install:
   - gem install rdiscount
   - gem install json
   - gem install parallel
-  - gem install execjs
   - gem install therubyracer -v 0.10.1
   - gem install rspec
   - gem install rake

data/README.md

@@ -34,12 +34,38 @@ Standard rubygems install should do:
 
     $ [sudo] gem install jsduck
 
-Windows users probably want to [download a binary release][winbin].
-
-See the [installation guide][] for help when you run into problems.
-
-[winbin]: https://sourceforge.net/projects/jsduck/files/
-[installation guide]: https://github.com/senchalabs/jsduck/wiki/Installation
+If you encounter errors during gem installation, you may need to
+install the header files for compiling extension modules for Ruby 1.9.
+For Debian systems you'll need the `ruby1.9-dev` package.  For Red Hat
+/ CentOS / Fedora use the `ruby-devel` package.
+
+In **OSX Mountain Lion** the compilation of `therubyracer` dependency
+often fails for so far unknown reasons.  Most users have found a
+solution in upgrading to Ruby 1.9 using [RVM][].
+
+For **Windows** users out there, you can download the binary version,
+which includes Ruby interpreter and all dependencies bundled in a
+single .exe file.  Grab it from the [download page][].
+
+Alternatively you can install through rubygems, but you need to do
+some additional tweaks. First go and [download][libs download]
+therubyracer gem and v8 lib that stereobooster has built for
+windows. You need to install this special rubyracer version instead of
+the one from rubygems:
+
+    > gem install therubyracer-0.11.0beta1-x86-mingw32.gem
+
+To make it actually work you need `v8.dll` somewhere in your
+system. Extract the `lib_v8.3.11.9.zip` take the `v8.dll` inside it
+and place into the `bin` directory of your Ruby installation (other
+dirs that are on your PATH can work too, but I've found this to be the
+most sensible place to put it). Now you're ready to install JSDuck:
+
+    > gem install jsduck
+
+[RVM]: https://rvm.io/
+[download page]: https://sourceforge.net/projects/jsduck/files/
+[libs download]: https://github.com/stereobooster/therubyracer/downloads
 
 Usage
 -----

data/Rakefile

@@ -104,7 +104,7 @@ def compress
   dir = "template-min"
 
   # Create JSB3 file for Docs app
-  system("sencha", "create", "jsb", "-a", "http://localhost/docs/", "-p", "#{dir}/app.jsb3")
+  system("sencha", "create", "jsb", "-a", "http://localhost/~renesaarsoo/docs/", "-p", "#{dir}/app.jsb3")
   # Concatenate files listed in JSB3 file
   system("sencha", "build", "-p", "#{dir}/app.jsb3", "-d", dir)
 
@@ -159,11 +159,6 @@ class JsDuckRunner
     add_options("--comments-domain", db_name+"/"+version)
   end
 
-  def add_search(product, version)
-    add_options("--search-url", "http://support-test.sencha.com:8080/docsearch/search")
-    add_options("--search-domain", product+"/"+version)
-  end
-
   def add_ext4
     @options += [
       "--title", "Sencha Docs - Ext JS 4.0",
@@ -252,7 +247,7 @@ task :ext4 => :sass do
   runner.add_debug
   runner.run
 
-  system("ln -s #{EXT_BUILD} #{OUT_DIR}/extjs-build")
+  system("cp -r #{EXT_BUILD} #{OUT_DIR}/extjs-build")
 end
 
 desc "Run JSDuck on Ext JS from SDK repo (for internal use at Sencha)"
@@ -262,14 +257,15 @@ task :sdk => :sass do
     "--output", OUT_DIR,
     "--config", "#{SDK_DIR}/extjs/docs/config.json",
     "--examples-base-url", "extjs-build/examples/",
+    # "--import", "4.1:../docs.sencha.com/exports/extjs-4.1.1",
+    # "--import", "4.2",
     "--seo"
   )
   runner.add_debug
   runner.add_comments('ext-js', '4')
-  runner.add_search('Ext JS', '4.2.0')
   runner.run
 
-  system("ln -s #{EXT_BUILD} #{OUT_DIR}/extjs-build")
+  system("cp -r #{EXT_BUILD} #{OUT_DIR}/extjs-build")
 end
 
 desc "Run JSDuck on Sencha Touch 2 repo (for internal use at Sencha)"
@@ -279,14 +275,10 @@ task :touch2 => :sass do
     "--output", OUT_DIR,
     "--config", "#{SDK_DIR}/touch/docs/config.json",
     "--examples-base-url", "touch-build/examples/production/",
-    # "--import", "1.1.0:../docs.sencha.com/exports/touch-1.1.0",
-    # "--import", "1.1.1:../docs.sencha.com/exports/touch-1.1.1",
-    # "--import", "2.0.0:../docs.sencha.com/exports/touch-2.0.0",
-    # "--import", "2.0.1:../docs.sencha.com/exports/touch-2.0.1",
-    # "--import", "2.1.0:../docs.sencha.com/exports/touch-2.1.0",
-    # "--import", "2.1.1:../docs.sencha.com/exports/touch-2.1.1",
-    # "--import", "2.2.0:../docs.sencha.com/exports/touch-2.2.0",
-    # "--import", "2.2.1",
+    # "--import", "Touch 1.1:../docs.sencha.com/exports/touch-1.1",
+    # "--import", "Touch 2.0:../docs.sencha.com/exports/touch-2.0.1",
+    # "--import", "Touch 2.1.0:../docs.sencha.com/exports/touch-2.1.0",
+    # "--import", "Touch 2.1.1",
     "--seo"
   )
 
@@ -294,7 +286,7 @@ task :touch2 => :sass do
   runner.add_comments('touch', '2')
   runner.run
 
-  system("ln -s #{TOUCH_BUILD} #{OUT_DIR}/touch-build")
+  system("cp -r #{TOUCH_BUILD} #{OUT_DIR}/touch-build")
 end
 
 task :default => :spec

data/bin/compare

@@ -105,7 +105,7 @@ def read_ignored_members(filename)
 end
 
 def normal_public_member?(m)
-  !m["private"] && !m["meta"]["protected"] && !m["meta"]["deprecated"] && !m["meta"]["removed"]
+  !m["private"] && !m["protected"] && !m["deprecated"] && !m["removed"]
 end
 
 def unify_default(v)
@@ -115,7 +115,7 @@ end
 def visibility(m)
   if m["private"]
     "private"
-  elsif m["meta"]["protected"]
+  elsif m["protected"]
     "protected"
   else
     "public"
@@ -125,7 +125,7 @@ end
 # Finds equivalent member to given member from class.
 # Returns the member found or nil.
 def find_member(cls, member)
-  cls[member["meta"]["static"] ? "statics" : "members"][member["tagname"]].find do |m|
+  cls[member["static"] ? "statics" : "members"][member["tagname"]].find do |m|
     member["name"] == m["name"]
   end
 end
@@ -190,9 +190,9 @@ def compare_classes(cls1, cls2)
         :what => "removed",
         :other => other ? {
           :type => other["tagname"],
-          :static => other["meta"]["static"],
+          :static => other["static"],
           :private => other["private"],
-          :protected => other["meta"]["protected"],
+          :protected => other["protected"],
         } : nil
       }
     end

data/bin/jsduck

@@ -17,11 +17,10 @@
 # For running when gem not installed
 $:.unshift File.dirname(File.dirname(__FILE__)) + "/lib"
 
+require 'rubygems'
 require 'jsduck/app'
 require 'jsduck/options'
 
 opts = JsDuck::Options.new
 opts.parse!(ARGV)
-exit_code = JsDuck::App.new(opts).run
-
-exit exit_code
+JsDuck::App.new(opts).run

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.10.4'
-  s.date = Time.new.strftime('%Y-%m-%d')
+  s.version = '5.0.0.beta01'
+  s.date = '2013-02-25'
   s.summary = "Simple JavaScript Duckumentation generator"
   s.description = "Documentation generator for Sencha JS frameworks"
   s.homepage = "https://github.com/senchalabs/jsduck"
@@ -22,8 +22,7 @@ Gem::Specification.new do |s|
   s.add_dependency 'rdiscount'
   s.add_dependency 'json'
   s.add_dependency 'parallel'
-  s.add_dependency 'execjs'
-  s.add_dependency 'therubyracer', '>= 0.10.0'
+  s.add_dependency 'therubyracer', '>= 0.10.0', '< 0.11.0'
   s.add_dependency 'dimensions'
 
   s.add_development_dependency 'rspec'

data/lib/jsduck/aggregator.rb

@@ -1,16 +1,14 @@
-require 'jsduck/class'
-require 'jsduck/accessors'
 require 'jsduck/logger'
-require 'jsduck/enum'
-require 'jsduck/override'
 
 module JsDuck
 
-  # Combines JavaScript Parser, DocParser and Merger.
-  # Produces array of classes as result.
+  # Groups parsed documentation data from source files into classes.
+  #
+  # Produces Hash of classes as result.  When a member is found that
+  # doesn't belong to any class, it's placed into special "global"
+  # class.
   class Aggregator
     def initialize
-      @documentation = []
       @classes = {}
       @alt_names = {}
       @orphans = []
@@ -28,6 +26,18 @@ module JsDuck
       file.each {|doc| register(doc) }
     end
 
+    # Returns the final result which is a Hash of all classes indexed
+    # by name.  It's a hash because some processors applied to this
+    # returned classes list need a random-access look up classes by
+    # name.
+    def result
+      classify_orphans
+      create_global_class
+      @classes
+    end
+
+    private
+
     # Registers documentation node either as class or as member of
     # some class.
     def register(node)
@@ -52,7 +62,6 @@ module JsDuck
         @current_class = old_cls
       else
         @current_class = cls
-        @documentation << cls
         @classes[cls[:name]] = cls
 
         # Register all alternate names of class for lookup too
@@ -67,7 +76,6 @@ module JsDuck
             # it by merging the class with alt-name into this class.
             if @classes[altname]
               merge_classes(cls, @classes[altname])
-              @documentation.delete(@classes[altname])
               @classes.delete(altname)
               warn_alt_name(cls)
             end
@@ -91,12 +99,8 @@ module JsDuck
         old[tag] = old[tag] || new[tag]
       end
       # Merge arrays
-      [:mixins, :alternateClassNames, :files].each do |tag|
-        old[tag] = old[tag] + new[tag]
-      end
-      # Merge meta hashes
-      new[:meta].each_pair do |name, value|
-        old[:meta][name] = old[:meta][name] || value
+      [:mixins, :alternateClassNames, :requires, :uses, :files].each do |tag|
+        old[tag] = (old[tag] || []) + (new[tag] || [])
       end
       # Merge hashes of arrays
       [:aliases].each do |tag|
@@ -120,7 +124,7 @@ module JsDuck
     # When no class precedes them - they too are orphaned.
     def add_member(node)
       # Completely ignore member if @ignore used
-      return if node[:meta][:ignore]
+      return if node[:ignore]
 
       if node[:owner]
         if @classes[node[:owner]]
@@ -156,9 +160,7 @@ module JsDuck
     # Creates classes for orphans that have :owner property defined,
     # and then inserts orphans to these classes.
     def classify_orphans
-      # Clone the orphans array first to avoid problems with
-      # #inster_orphan method deleting items from @orphans array.
-      @orphans.clone.each do |orph|
+      @orphans.each do |orph|
         if orph[:owner]
           class_name = orph[:owner]
           if !@classes[class_name]
@@ -187,73 +189,12 @@ module JsDuck
         :tagname => :class,
         :name => name,
         :doc => doc,
-        :mixins => [],
         :alternateClassNames => [],
         :members => [],
         :aliases => {},
-        :meta => {},
         :files => [{:filename => "", :linenr => 0, :href => ""}],
       })
     end
-
-    # Gets rid of classes marked with @ignore
-    def remove_ignored_classes
-      @documentation.delete_if do |cls|
-        if cls[:meta][:ignore]
-          @classes.delete(cls["name"])
-          true
-        end
-      end
-    end
-
-    # Appends Ext4 options parameter to each event parameter list.
-    def append_ext4_event_options
-      options = {
-        :tagname => :param,
-        :name => "eOpts",
-        :type => "Object",
-        :doc => "The options object passed to {@link Ext.util.Observable#addListener}."
-      }
-      @classes.each_value do |cls|
-        cls[:members].each do |m|
-          m[:params] << options if m[:tagname] == :event
-        end
-      end
-    end
-
-    # Creates accessor method for configs marked with @accessor
-    def create_accessors
-      accessors = Accessors.new
-      @classes.each_value do |cls|
-        accessors.create(cls)
-      end
-    end
-
-    # Loops through all enums and auto-detects their types if needed.
-    def process_enums
-      Enum.new(@classes).process_all!
-    end
-
-    # Processes all overrides.
-    # Returns list of override classes.
-    def process_overrides
-      Override.new(@classes).process_all!.map do |cls|
-        # discard each override class
-        @classes.delete(cls[:name])
-        @documentation.delete(cls)
-        cls
-      end
-    end
-
-    # Are we dealing with ExtJS 4?
-    # True if any of the classes is defined with Ext.define()
-    def ext4?
-      @documentation.any? {|cls| cls[:code_type] == :ext_define }
-    end
-
-    def result
-      @documentation + @orphans
-    end
   end
 
 end

data/lib/jsduck/app.rb

@@ -1,9 +1,9 @@
 require 'jsduck/batch_parser'
+require 'jsduck/batch_processor'
 require 'jsduck/assets'
-require 'jsduck/meta_tag_registry'
+require 'jsduck/tag_registry'
 require 'jsduck/export_writer'
 require 'jsduck/web_writer'
-require 'jsduck/logger'
 
 module JsDuck
 
@@ -15,7 +15,6 @@ module JsDuck
     end
 
     # Main App logic.
-    # Returns application exit code.
     def run
       parse
 
@@ -26,27 +25,21 @@ module JsDuck
       else
         generate_web_page
       end
-
-      if @opts.warnings_exit_nonzero && Logger.warnings_logged?
-        return 2
-      else
-        return 0
-      end
     end
 
     private
 
     def parse
-      @batch_parser = BatchParser.new(@opts)
-      @relations = @batch_parser.run
+      @parsed_files = BatchParser.parse(@opts)
+      @relations = BatchProcessor.process(@parsed_files, @opts)
     end
 
     def init_assets
       # Initialize guides, videos, examples, ...
       @assets = Assets.new(@relations, @opts)
 
-      # Give access to assets from all meta-tags
-      MetaTagRegistry.instance.assets = @assets
+      # HACK: Give access to assets from @aside tag
+      TagRegistry.get_by_name(:aside).assets = @assets
     end
 
     def generate_export
@@ -54,7 +47,7 @@ module JsDuck
     end
 
     def generate_web_page
-      WebWriter.new(@relations, @assets, @batch_parser.parsed_files, @opts).write
+      WebWriter.new(@relations, @assets, @parsed_files, @opts).write
     end
 
   end

data/lib/jsduck/app_data.rb

@@ -1,7 +1,7 @@
 require 'jsduck/util/json'
 require 'jsduck/icons'
 require 'jsduck/search_data'
-require 'jsduck/meta_tag_registry'
+require 'jsduck/tag_registry'
 
 module JsDuck
 
@@ -21,17 +21,16 @@ module JsDuck
           :guides => @assets.guides.to_array,
           :videos => @assets.videos.to_array,
           :examples => @assets.examples.to_array,
-          :search => SearchData.new.create(@relations.classes, @assets, @opts),
-          :guideSearch => @opts.search,
+          :search => SearchData.new.create(@relations.classes, @assets),
           :tests => @opts.tests,
-          :signatures => MetaTagRegistry.instance.signatures,
+          :signatures => TagRegistry.signatures,
+          :memberTypes => TagRegistry.member_types,
           :localStorageDb => @opts.local_storage_db,
           :showPrintButton => @opts.seo,
           :touchExamplesUi => @opts.touch_examples_ui,
           :source => @opts.source,
           :commentsUrl => @opts.comments_url,
           :commentsDomain => @opts.comments_domain,
-          :message => @opts.message,
         }
       }) + ";\n"
       File.open(filename, 'w') {|f| f.write(js) }