jsduck 5.0.0.beta01 → 5.0.0.beta2

data/.travis.yml

@@ -6,6 +6,7 @@ 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,38 +34,12 @@ Standard rubygems install should do:
 
     $ [sudo] gem install jsduck
 
-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
+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
 
 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/~renesaarsoo/docs/", "-p", "#{dir}/app.jsb3")
+  system("sencha", "create", "jsb", "-a", "http://localhost/docs/", "-p", "#{dir}/app.jsb3")
   # Concatenate files listed in JSB3 file
   system("sencha", "build", "-p", "#{dir}/app.jsb3", "-d", dir)
 
@@ -247,7 +247,7 @@ task :ext4 => :sass do
   runner.add_debug
   runner.run
 
-  system("cp -r #{EXT_BUILD} #{OUT_DIR}/extjs-build")
+  system("ln -s #{EXT_BUILD} #{OUT_DIR}/extjs-build")
 end
 
 desc "Run JSDuck on Ext JS from SDK repo (for internal use at Sencha)"
@@ -257,7 +257,7 @@ 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.1.3:../docs.sencha.com/exports/extjs-4.1.3",
     # "--import", "4.2",
     "--seo"
   )
@@ -265,7 +265,7 @@ task :sdk => :sass do
   runner.add_comments('ext-js', '4')
   runner.run
 
-  system("cp -r #{EXT_BUILD} #{OUT_DIR}/extjs-build")
+  system("ln -s #{EXT_BUILD} #{OUT_DIR}/extjs-build")
 end
 
 desc "Run JSDuck on Sencha Touch 2 repo (for internal use at Sencha)"
@@ -286,7 +286,7 @@ task :touch2 => :sass do
   runner.add_comments('touch', '2')
   runner.run
 
-  system("cp -r #{TOUCH_BUILD} #{OUT_DIR}/touch-build")
+  system("ln -s #{TOUCH_BUILD} #{OUT_DIR}/touch-build")
 end
 
 task :default => :spec

data/bin/jsduck

@@ -17,7 +17,6 @@
 # For running when gem not installed
 $:.unshift File.dirname(File.dirname(__FILE__)) + "/lib"
 
-require 'rubygems'
 require 'jsduck/app'
 require 'jsduck/options'
 

data/js-classes/String.js

@@ -125,7 +125,7 @@
  *
  *     String.fromCharCode(65,66,67)
  *
- * @param {Number} num1, ..., numN A sequence of numbers that are Unicode values.
+ * @param {Number...} numbers A sequence of numbers that are Unicode values.
  * @return {String} String containing characters from encoding.
  */
 
@@ -359,9 +359,7 @@
 
 /**
  * @method concat
- * Combines the text of two strings and returns a new string.
- *
- * `concat` combines the text from one or more strings and returns a new string. Changes to the text in
+ * Combines combines the text from one or more strings and returns a new string. Changes to the text in
  * one string do not affect the other string.
  *
  * The following example combines strings into a new string.
@@ -369,7 +367,7 @@
  *     var hello = "Hello, ";
  *     console.log(hello.concat("Kevin", " have a nice day.")); // Hello, Kevin have a nice day.
  *
- * @param {String} string2...stringN
+ * @param {String...} strings The strings to concatenate.
  * @return {String} Result of both strings.
  */
 

data/jsduck.gemspec

@@ -2,8 +2,8 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = ">= 1.3.5"
 
   s.name = 'jsduck'
-  s.version = '5.0.0.beta01'
-  s.date = '2013-02-25'
+  s.version = '5.0.0.beta2'
+  s.date = Time.new.strftime('%Y-%m-%d')
   s.summary = "Simple JavaScript Duckumentation generator"
   s.description = "Documentation generator for Sencha JS frameworks"
   s.homepage = "https://github.com/senchalabs/jsduck"
@@ -22,6 +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', '< 0.11.0'
   s.add_dependency 'dimensions'
 

data/lib/jsduck/aggregator.rb

@@ -87,9 +87,7 @@ module JsDuck
     end
 
     def warn_alt_name(cls)
-      file = cls[:files][0][:filename]
-      line = cls[:files][0][:linenr]
-      Logger.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", cls[:files][0])
     end
 
     # Merges new class-doc into old one.

data/lib/jsduck/app.rb

@@ -3,7 +3,7 @@ require 'jsduck/batch_processor'
 require 'jsduck/assets'
 require 'jsduck/tag_registry'
 require 'jsduck/export_writer'
-require 'jsduck/web_writer'
+require 'jsduck/web/writer'
 
 module JsDuck
 
@@ -47,7 +47,7 @@ module JsDuck
     end
 
     def generate_web_page
-      WebWriter.new(@relations, @assets, @parsed_files, @opts).write
+      Web::Writer.new(@relations, @assets, @parsed_files, @opts).write
     end
 
   end

data/lib/jsduck/categories/file.rb

@@ -15,12 +15,6 @@ module JsDuck
       def generate
         @categories = Util::Json.read(@filename)
 
-        # Don't crash if old syntax is used.
-        if @categories.is_a?(Hash) && @categories["categories"]
-          Logger.warn(nil, 'Update categories file to contain just the array inside {"categories": [...]}', @filename)
-          @categories = @categories["categories"]
-        end
-
         # Perform expansion on all class names containing * wildcard
         @categories.each do |cat|
           cat["groups"].each do |group|

data/lib/jsduck/class.rb

@@ -115,8 +115,7 @@ module JsDuck
         # simplest thing and ignore it.
         Class.new({:name => classname}, false)
       else
-        context = @doc[:files][0]
-        Logger.warn(:extend, "Class #{classname} not found", context[:filename], context[:linenr])
+        Logger.warn(:extend, "Class #{classname} not found", @doc[:files][0])
         # Create placeholder class
         Class.new({:name => classname}, false)
       end

data/lib/jsduck/doc/parser.rb

@@ -27,10 +27,10 @@ module JsDuck
     # JsDuck::DocFormatter.
     #
     class Parser < Doc::Scanner
-      def parse(input, filename="", linenr=0)
-        @filename = filename
-        @linenr = linenr
+      def parse(input, filename="", linenr = 0)
+        @position = {:filename => filename, :linenr => linenr}
         @tags = []
+        @non_repeatable_tags = {}
         @input = StringScanner.new(Doc::Comment.purify(input))
 
         parse_loop
@@ -86,16 +86,23 @@ module JsDuck
           match(/\w+/)
           hw # Skip the whitespace right after the tag.
 
-          tags = tag.parse_doc(self)
+          tags = tag.parse_doc(self, @position)
           if tags.is_a?(Hash)
             add_tag(tags)
           elsif tags.is_a?(Array)
             tags.each {|t| add_tag(t) }
           end
 
+          if !tag.repeatable
+            if @non_repeatable_tags[name]
+              warn(:tag_repeated, "@#{name} tag can occur only once per doc-comment")
+            end
+            @non_repeatable_tags[name] = true
+          end
+
           skip_white
         else
-          Logger.warn(:tag, "Unsupported tag: @#{name}", @filename, @linenr)
+          warn(:tag, "Unsupported tag: @#{name}")
           @multiline_tag[:doc] += "@"
         end
       end

data/lib/jsduck/doc/scanner.rb

@@ -16,6 +16,7 @@ module JsDuck
         @ident_chain_pattern = /[$\w-]+(\.[$\w-]+)*/
 
         @input = nil # set to StringScanner in subclass
+        @position = {} # set in subclass
       end
 
       # Provides access to StringScanner
@@ -70,6 +71,11 @@ module JsDuck
         self
       end
 
+      # Prints a warning message
+      def warn(type, msg)
+        Logger.warn(type, msg, @position)
+      end
+
     end
 
   end

data/lib/jsduck/doc/standard_tag_parser.rb

@@ -30,6 +30,7 @@ module JsDuck
       # were specified and how their matching succeeded.
       #
       def parse(cfg)
+        @tagname = cfg[:tagname]
         tag = {:tagname => cfg[:tagname]}
         add_type(tag) if cfg[:type]
         add_name_with_default(tag) if cfg[:name]
@@ -61,7 +62,7 @@ module JsDuck
           optional = nil
         end
 
-        match(/\}/)
+        match(/\}/) or warn("@#{@tagname} tag syntax: '}' expected")
 
         return {:type => name, :optional => optional}
       end
@@ -71,10 +72,10 @@ module JsDuck
         if hw.match(/\[/)
           tag[:name] = hw.ident_chain
           if hw.match(/=/)
-          hw
-          tag[:default] = default_value
-        end
-        hw.match(/\]/)
+            hw
+            tag[:default] = default_value
+          end
+          hw.match(/\]/) or warn("@#{@tagname} tag syntax: ']' expected")
           tag[:optional] = true
         else
           tag[:name] = hw.ident_chain
@@ -148,6 +149,10 @@ module JsDuck
       def hw
         @ds.hw
       end
+
+      def warn(msg)
+        @ds.warn(:tag_syntax, msg)
+      end
     end
 
   end

data/lib/jsduck/doc/subproperties.rb

@@ -28,6 +28,8 @@ module JsDuck
       def nest(raw_items, pos)
         # First item can't be namespaced, if it is ignore the rest.
         if raw_items[0] && raw_items[0][:name] =~ /\./
+          warn(raw_items[0][:name], pos)
+          raw_items[0][:name].sub!(/\..*$/, '')
           return [raw_items[0]]
         end
 
@@ -47,8 +49,7 @@ module JsDuck
               parent[:properties] = [] unless parent[:properties]
               parent[:properties] << it
             else
-              msg = "Ignoring subproperty #{$1}.#{$2}, no parent found with name '#{$1}'."
-              Logger.warn(:subproperty, msg, pos[:filename], pos[:linenr])
+              warn("#{$1}.#{$2}", pos)
             end
           else
             items << it
@@ -58,6 +59,12 @@ module JsDuck
         return items
       end
 
+      def warn(name, pos)
+        parent = name.sub(/\.[^.]*$/, '')
+        msg = "Ignoring subproperty '#{name}' not parent found with name '#{parent}'."
+        Logger.warn(:subproperty, msg, pos)
+      end
+
     end
 
   end

data/lib/jsduck/docs_code_comparer.rb

@@ -7,16 +7,23 @@ module JsDuck
   class DocsCodeComparer
     include Util::Singleton
 
-    # When docs has the key, returns value from there.
-    # When code has the key and matches with docs, gets value from there.
-    # Otherwise returns nil.
-    def merge_if_matches(key, docs, code)
+    # Sets the value of a field in result hash based on its value in
+    # docs and code hashes.
+    #
+    # - When docs has the key, gets value from there.
+    #
+    # - When code has the key and matches with docs, gets value from
+    #   there, and also remembers the fact that we're using
+    #   auto-detected value by recording it in :autodetected field.
+    #
+    def merge_if_matches(h, key, docs, code)
       if docs[key]
-        docs[key]
+        h[key] = docs[key]
       elsif code[key] && matches?(docs, code)
-        code[key]
+        h[key] = code[key]
+        mark_autodetected(h, key)
       else
-        nil
+        # nothing
       end
     end
 
@@ -26,6 +33,12 @@ module JsDuck
       return docs[:name] == nil || docs[:name] == code[:name]
     end
 
+    # Stores the key as flag into h[:autodetcted]
+    def mark_autodetected(h, key)
+      h[:autodetected] = {} unless h[:autodetected]
+      h[:autodetected][key] = true
+    end
+
   end
 
 end

data/lib/jsduck/exporter/app.rb

@@ -6,17 +6,31 @@ module JsDuck
   module Exporter
 
     # Exports data for Docs app.
-    class App < Full
+    class App
       def initialize(relations, opts)
-        super(relations, opts)
+        @full_exporter = Exporter::Full.new(relations, opts)
+        @relations = relations
         @renderer = Render::Class.new(opts)
       end
 
       # Returns compacted class data hash which contains an additional
       # :html field with full HTML to show on class overview page.
       def export(cls)
-        data = super(cls)
+        data = @full_exporter.export(cls)
+
+        data[:component] = cls.inherits_from?("Ext.Component")
+        data[:superclasses] = cls.superclasses.collect {|c| c[:name] }
+        data[:subclasses] = @relations.subclasses(cls).collect {|c| c[:name] }.sort
+        data[:mixedInto] = @relations.mixed_into(cls).collect {|c| c[:name] }.sort
+        data[:alternateClassNames] = cls[:alternateClassNames].sort if cls[:alternateClassNames]
+
+        data[:mixins] = cls.deps(:mixins).collect {|c| c[:name] }.sort
+        data[:parentMixins] = cls.parent_deps(:mixins).collect {|c| c[:name] }.sort
+        data[:requires] = cls.deps(:requires).collect {|c| c[:name] }.sort
+        data[:uses] = cls.deps(:uses).collect {|c| c[:name] }.sort
+
         data[:html] = @renderer.render(data)
+
         return compact(data)
       end
 
@@ -25,21 +39,12 @@ module JsDuck
       # removes extra data from export
       def compact(cls)
         cls.delete(:doc)
-        cls[:members] = compact_members_group(cls[:members])
-        cls[:statics] = compact_members_group(cls[:statics])
+        cls[:members] = cls[:members].map {|m| compact_member(m) }
         cls[:files] = compact_files(cls[:files])
         cls[:meta] = combine_meta(cls)
         cls
       end
 
-      def compact_members_group(group)
-        c_group = {}
-        group.each_pair do |type, members|
-          c_group[type] = members.map {|m| compact_member(m) }
-        end
-        c_group
-      end
-
       def compact_member(m)
         m_copy = {}
         [:name, :tagname, :owner, :id].each do |key|