jsduck 3.10.5 → 3.11.0

data/README.md

@@ -1,9 +1,9 @@
-JsDuck
+JSDuck
 ======
 
 API documentation generator for Sencha JavaScript frameworks.
 
-JsDuck aims to be a better documentation generator for [Ext JS][] than
+JSDuck aims to be a better documentation generator for [Ext JS][] than
 the old [ext-doc][] was. It is used by Sencha to document [Ext JS
 4][ext4-docs], [Sencha Touch][touch2-docs] and [several other][other-docs]
 products.
@@ -108,13 +108,26 @@ Hacking it
 See [Hacking guide](https://github.com/senchalabs/jsduck/wiki/Hacking) in wiki.
 
 
+Who's using JSDuck?
+-------------------
+
+- Appcelerator [Titanium SDK](http://docs.appcelerator.com/titanium/2.0/index.html)
+- AT&T [API Platform SDK for HTML5](https://code-api-att.com/SenchaSdk20Drop23Docs/)
+- Bryntum [Siesta unit testing framework](http://www.bryntum.com/products/siesta/docs/)
+- [GeoExt 2](https://github.com/geoext/geoext2)
+- Rally Software [Rally App SDK](https://rally1.rallydev.com/apps/2.0p/doc/)
+- [Sencha](http://docs.sencha.com) - obviously :)
+
+These are some that we know of. Want your project listed here? Drop us a line.
+
+
 Copying
 -------
 
-JsDuck is distributed under the terms of the GNU General Public
+JSDuck is distributed under the terms of the GNU General Public
 License version 3.
 
-JsDuck was developed by [Rene Saarsoo](http://triin.net),
+JSDuck was developed by [Rene Saarsoo](http://triin.net),
 with many contributions from [Nick Poulden](https://github.com/nick).
 
 Thanks to [Ondřej Jirman](https://github.com/megous),
@@ -136,3 +149,12 @@ Changelog
 ---------
 
 See [Changelog](https://github.com/senchalabs/jsduck/wiki/Changelog) page in wiki.
+
+
+More questions?
+---------------
+
+Feel free to [post an issue][issues], but read the [FAQ][] first.
+
+[issues]: https://github.com/senchalabs/jsduck/issues
+[FAQ]: https://github.com/senchalabs/jsduck/wiki/FAQ

data/jsduck.gemspec

@@ -2,8 +2,8 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = ">= 1.3.5"
 
   s.name = 'jsduck'
-  s.version = '3.10.5'
-  s.date = '2012-05-23'
+  s.version = '3.11.0'
+  s.date = '2012-06-05'
   s.summary = "Simple JavaScript Duckumentation generator"
   s.description = "Documentation generator for Sencha JS frameworks"
   s.homepage = "https://github.com/senchalabs/jsduck"

data/lib/jsduck/class_formatter.rb

@@ -48,6 +48,7 @@ module JsDuck
       m[:html_type] = (@include_types && !is_css_tag) ? format_type(m[:type]) : m[:type] if m[:type]
       m[:params] = m[:params].map {|p| format_item(p, is_css_tag) } if m[:params]
       m[:return] = format_item(m[:return], is_css_tag) if m[:return]
+      m[:throws] = m[:throws].map {|t| format_item(t, is_css_tag) } if m[:throws]
       m[:properties] = m[:properties].map {|b| format_item(b, is_css_tag) } if m[:properties]
       m[:html_meta] = format_meta_data(m)
       m

data/lib/jsduck/css_lexer.rb

@@ -0,0 +1,201 @@
+require 'strscan'
+
+module JsDuck
+
+  # Tokenizes CSS or SCSS code into lexical tokens.
+  #
+  # Each token has a type and value.
+  # Types and possible values for them are as follows:
+  #
+  # - :number      -- "25.8"
+  # - :percentage  -- "25%"
+  # - :dimension   -- "2em"
+  # - :string      -- '"Hello world"'
+  # - :ident       -- "foo-bar"
+  # - :at_keyword  -- "@mixin"
+  # - :hash        -- "#00FF66"
+  # - :delim       -- "{"
+  # - :doc_comment -- "/** My comment */"
+  #
+  # Notice that doc-comments are recognized as tokens while normal
+  # comments are ignored just as whitespace.
+  #
+  class CssLexer
+    # Initializes lexer with input string.
+    def initialize(input)
+      @input = StringScanner.new(input)
+      @buffer = []
+    end
+
+    # Tests if given pattern matches the tokens that follow at current
+    # position.
+    #
+    # Takes list of strings and symbols.  Symbols are compared to
+    # token type, while strings to token value.  For example:
+    #
+    #     look(:ident, ":", :dimension)
+    #
+    def look(*tokens)
+      buffer_tokens(tokens.length)
+      i = 0
+      tokens.all? do |t|
+        tok = @buffer[i]
+        i += 1
+        if !tok
+          false
+        elsif t.instance_of?(Symbol)
+          tok[:type] == t
+        else
+          tok[:value] == t
+        end
+      end
+    end
+
+    # Returns the value of next token, moving the current token cursor
+    # also to next token.
+    #
+    # When full=true, returns full token as hash like so:
+    #
+    #     {:type => :ident, :value => "foo"}
+    #
+    # For doc-comments the full token also contains the field :linenr,
+    # pointing to the line where the doc-comment began.
+    #
+    def next(full=false)
+      buffer_tokens(1)
+      tok = @buffer.shift
+      # advance the scanpointer to the position after this token
+      @input.pos = tok[:pos]
+      full ? tok : tok[:value]
+    end
+
+    # True when no more tokens.
+    def empty?
+      buffer_tokens(1)
+      return !@buffer.first
+    end
+
+    # Ensures next n tokens are read in buffer
+    #
+    # At the end of buffering the initial position scanpointer is
+    # restored.  Only the #next method will advance the scanpointer in
+    # a way that's visible outside this class.
+    def buffer_tokens(n)
+      prev_pos = @input.pos
+      @input.pos = @buffer.last[:pos] if @buffer.last
+      (n - @buffer.length).times do
+        @previous_token = tok = next_token
+        if tok
+          # remember scanpointer position after each token
+          tok[:pos] = @input.pos
+          @buffer << tok
+        end
+      end
+      @input.pos = prev_pos
+    end
+
+    # Parses out next token from input stream.
+    def next_token
+      while !@input.eos? do
+        skip_white
+        if @input.check(IDENT)
+          return {
+            :type => :ident,
+            :value => @input.scan(IDENT)
+          }
+        elsif @input.check(/'/)
+          return {
+            :type => :string,
+            :value => @input.scan(/'([^'\\]|\\.)*('|\Z)/m)
+          }
+        elsif @input.check(/"/)
+          return {
+            :type => :string,
+            :value => @input.scan(/"([^"\\]|\\.)*("|\Z)/m)
+          }
+        elsif @input.check(/\//)
+          # Several things begin with dash:
+          # - comments, regexes, division-operators
+          if @input.check(/\/\*\*[^\/]/)
+            return {
+              :type => :doc_comment,
+              # Calculate current line number, starting with 1
+              :linenr => @input.string[0...@input.pos].count("\n") + 1,
+              :value => @input.scan_until(/\*\/|\Z/)
+            }
+          elsif @input.check(/\/\*/)
+            # skip multiline comment
+            @input.scan_until(/\*\/|\Z/)
+          elsif @input.check(/\/\//)
+            # skip line comment
+            @input.scan_until(/\n|\Z/)
+          else
+            return {
+              :type => :operator,
+              :value => @input.scan(/\//)
+            }
+          end
+        elsif @input.check(NUM)
+          nr = @input.scan(NUM)
+          if @input.check(/%/)
+            return {
+              :type => :percentage,
+              :value => nr + @input.scan(/%/)
+            }
+          elsif @input.check(IDENT)
+            return {
+              :type => :dimension,
+              :value => nr + @input.scan(IDENT)
+            }
+          else
+            return {
+              :type => :number,
+              :value => nr
+            }
+          end
+        elsif @input.check(/@/)
+          return maybe(:at_keyword, /@/, IDENT)
+        elsif @input.check(/#/)
+          return maybe(:hash, /#/, NAME)
+        elsif @input.check(/\$/)
+          return maybe(:var, /\$/, IDENT)
+        elsif @input.check(/./)
+          return {
+            :type => :delim,
+            :value => @input.scan(/./)
+          }
+        end
+      end
+    end
+
+    # Returns token of given type when both regexes match.
+    # Otherwise returns :delim token with value of first regex match.
+    # First regex must always match.
+    def maybe(token_type, before_re, after_re)
+      before = @input.scan(before_re)
+      if @input.check(after_re)
+        return {
+          :type => token_type,
+          :value => before + @input.scan(after_re)
+        }
+      else
+        return {
+          :type => :delim,
+          :value => before
+        }
+      end
+    end
+
+    def skip_white
+      @input.scan(/\s+/)
+    end
+
+    # Simplified token syntax based on:
+    # http://www.w3.org/TR/CSS21/syndata.html
+    IDENT = /-?[_a-z][_a-z0-9-]*/i
+    NAME = /[_a-z0-9-]+/i
+    NUM = /[0-9]*\.[0-9]+|[0-9]+/
+
+  end
+
+end

data/lib/jsduck/css_parser.rb

@@ -1,11 +1,11 @@
-require 'jsduck/lexer'
+require 'jsduck/css_lexer'
 require 'jsduck/doc_parser'
 
 module JsDuck
 
   class CssParser
     def initialize(input, options = {})
-      @lex = Lexer.new(input)
+      @lex = CssLexer.new(input)
       @doc_parser = DocParser.new
       @docs = []
     end
@@ -28,31 +28,77 @@ module JsDuck
       @docs
     end
 
-    # <code-block> := <mixin> | <nop>
+    # <code-block> := <mixin-declaration> | <var-declaration> | <nop>
     def code_block
-      if look("@", "mixin")
-        mixin
+      if look("@mixin")
+        mixin_declaration
+      elsif look(:var, ":")
+        var_declaration
       else
         {:type => :nop}
       end
     end
 
-    # <mixin> := "@mixin" <css-ident>
-    def mixin
-      match("@", "mixin")
+    # <mixin-declaration> := "@mixin" <ident>
+    def mixin_declaration
+      match("@mixin")
       return {
         :type => :css_mixin,
-        :name => look(:ident) ? css_ident : nil,
+        :name => look(:ident) ? match(:ident) : nil,
       }
     end
 
-    # <css-ident> := <ident>  [ "-" <ident> ]*
-    def css_ident
-      chain = [match(:ident)]
-      while look("-", :ident) do
-        chain << match("-", :ident)
+    # <var-declaration> := <var> ":" <css-value>
+    def var_declaration
+      name = match(:var)
+      match(":")
+      value_list = css_value
+      return {
+        :type => :css_var,
+        :name => name,
+        :value => {
+          :default => value_list.map {|v| v[:value] }.join(" "),
+          :type => value_type(value_list),
+        }
+      }
+    end
+
+    # <css-value> := ...anything up to... [ ";" | "}" | "!default" ]
+    def css_value
+      val = []
+      while !look(";") && !look("}") && !look("!", "default")
+        val << @lex.next(true)
+      end
+      val
+    end
+
+    # Determines type of CSS value
+    def value_type(val)
+      case val[0][:type]
+      when :number
+        "number"
+      when :dimension
+        "length"
+      when :percentage
+        "percentage"
+      when :string
+        "string"
+      when :hash
+        "color"
+      when :ident
+        case val[0][:value]
+        when "true", "false"
+          return "boolean"
+        when "rgb", "rgba", "hsl", "hsla"
+          return "color"
+        when "black", "silver", "gray", "white", "maroon",
+          "red", "purple", "fuchsia", "green", "lime", "olive",
+          "yellow", "navy", "blue", "teal", "aqua", "orange"
+          return "color"
+        when "transparent"
+          return "color"
+        end
       end
-      return chain.join("-")
     end
 
     # Matches all arguments, returns the value of last match

data/lib/jsduck/doc_parser.rb

@@ -132,6 +132,8 @@ module JsDuck
           at_alias
         elsif look(/@var\b/)
           at_var
+        elsif look(/@throws\b/)
+          at_throws
         elsif look(/@inheritable\b/)
           boolean_at_tag(/@inheritable/, :inheritable)
         elsif look(/@accessor\b/)
@@ -272,7 +274,15 @@ module JsDuck
       match(/@var/)
       add_tag(:css_var)
       maybe_type
-      maybe_name
+      maybe_name_with_default
+      skip_white
+    end
+
+    # matches @throws {type} ...
+    def at_throws
+      match(/@throws/)
+      add_tag(:throws)
+      maybe_type
       skip_white
     end
 

data/lib/jsduck/js_parser.rb

@@ -10,7 +10,18 @@ module JsDuck
       super(input)
       @doc_parser = DocParser.new
       @docs = []
-      @ext_namespaces = options[:ext_namespaces] || ["Ext"]
+      @ext_namespaces = (options[:ext_namespaces] || ["Ext"]).map {|ns| tokenize_ns(ns) }
+    end
+
+    # Splits namespace string into array like so:
+    #
+    # "Foo.Bar.Baz" --> ["Foo", ".", "Bar", ".", "Baz"]
+    #
+    def tokenize_ns(ns)
+      ns.split(".").reduce([]) do |res, x|
+        res << "." unless res.length == 0
+        res << x
+      end
     end
 
     # Parses the whole JavaScript block and returns array where for
@@ -78,9 +89,9 @@ module JsDuck
       elsif look(:var)
         var_declaration
       elsif ext_look(:ns, ".", "define", "(", :string)
-        ext_define
+        ext_define(:ns, ".", "define", "(", :string)
       elsif ext_look(:ns, ".", "ClassManager", ".", "create", "(", :string)
-        ext_define
+        ext_define(:ns, ".", "ClassManager", ".", "create", "(", :string)
       elsif look(:ident, ":") || look(:string, ":")
         property_literal
       elsif look(",", :ident, ":") || look(",", :string, ":")
@@ -244,10 +255,8 @@ module JsDuck
     end
 
     # <ext-define> := "Ext" "." ["define" | "ClassManager" "." "create" ] "(" <string> "," <ext-define-cfg>
-    def ext_define
-      match(:ident, ".");
-      look("define") ? match("define") : match("ClassManager", ".", "create");
-      name = match("(", :string)[:value]
+    def ext_define(*pattern)
+      name = ext_match(*pattern)[:value]
 
       if look(",", "{")
         match(",")
@@ -400,11 +409,22 @@ module JsDuck
     # names listed in @ext_namespaces
     def ext_look(placeholder, *args)
       @ext_namespaces.each do |ns|
-        return true if look(ns, *args)
+        return true if look(*(ns + args))
       end
       return false
     end
 
+    # Like match() but tries as the first argument all the names
+    # listed in @ext_namespaces
+    def ext_match(placeholder, *args)
+      @ext_namespaces.each do |ns|
+        pattern = ns + args
+        if look(*pattern)
+          return match(*pattern)
+        end
+      end
+    end
+
   end
 
 end

data/lib/jsduck/merger.rb

@@ -63,6 +63,8 @@ module JsDuck
         :class
       elsif code[:type] == :css_mixin
         :css_mixin
+      elsif code[:type] == :css_var
+        :css_var
       elsif doc_map[:cfg]
         :cfg
       elsif code[:type] == :function
@@ -160,6 +162,7 @@ module JsDuck
         :doc => detect_doc(docs),
         :params => detect_params(:method, doc_map, code),
         :return => detect_return(doc_map, name == "constructor" ? "Object" : "undefined"),
+        :throws => detect_throws(doc_map),
       }, doc_map)
     end
 
@@ -209,6 +212,7 @@ module JsDuck
         :name => detect_name(:css_var, doc_map, code),
         :owner => detect_owner(doc_map),
         :type => detect_type(:css_var, doc_map, code),
+        :default => detect_default(:css_var, doc_map, code),
         :doc => detect_doc(docs),
       }, doc_map)
     end
@@ -251,7 +255,7 @@ module JsDuck
         main_tag[:name]
       elsif doc_map[:constructor]
         "constructor"
-      elsif code[:type] == :function || code[:type] == :css_mixin
+      elsif code[:type] == :function || code[:type] == :css_mixin || code[:type] == :css_var
         code[:name]
       elsif code[:type] == :assignment
         name_type == :full_name ? code[:left].join(".") : code[:left].last
@@ -285,6 +289,8 @@ module JsDuck
           elsif code[:right][:type] == :literal && code[:right][:class] != nil
             return code[:right][:class]
           end
+        elsif code[:type] == :css_var && code[:value][:type] != nil
+          return code[:value][:type]
         end
       end
       return "Object"
@@ -311,6 +317,8 @@ module JsDuck
         main_tag[:default]
       elsif code_matches_doc?(tagname, doc_map, code) && code[:type] == :assignment && code[:right]
         code[:right][:value]
+      elsif code_matches_doc?(tagname, doc_map, code) && code[:type] == :css_var && code[:value][:default]
+        code[:value][:default]
       end
     end
 
@@ -470,6 +478,17 @@ module JsDuck
       }
     end
 
+    def detect_throws(doc_map)
+      return unless doc_map[:throws]
+
+      doc_map[:throws].map do |throws|
+        {
+          :type => throws[:type] || "Object",
+          :doc => throws[:doc] || "",
+        }
+      end
+    end
+
     # Combines :doc-s of most tags
     # Ignores tags that have doc comment themselves and subproperty tags
     def detect_doc(docs)

data/lib/jsduck/options.rb

@@ -75,7 +75,7 @@ module JsDuck
       ]
       @meta_tag_paths = []
 
-      @version = "3.10.5"
+      @version = "3.11.0"
 
       # Customizing output
       @title = "Sencha Docs - Ext JS"

data/lib/jsduck/renderer.rb

@@ -318,6 +318,10 @@ module JsDuck
         doc << render_return(ret)
       end
 
+      if item[:throws]
+        doc << render_throws(item[:throws])
+      end
+
       doc
     end
 
@@ -351,6 +355,22 @@ module JsDuck
         "</ul>",
       ]
     end
+
+    def render_throws(throws)
+      return [
+        "<h3 class='pa'>Throws</h3>",
+        "<ul>",
+          throws.map do |thr|
+            [
+              "<li>",
+                "<span class='pre'>#{thr[:html_type]}</span>",
+                "<div class='sub-desc'>#{thr[:doc]}</div>",
+              "</li>",
+            ]
+          end,
+        "</ul>",
+      ]
+    end
   end
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jsduck
 version: !ruby/object:Gem::Version
-  version: 3.10.5
+  version: 3.11.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-23 00:00:00.000000000 Z
+date: 2012-06-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rdiscount
@@ -144,6 +144,7 @@ files:
 - lib/jsduck/class.rb
 - lib/jsduck/class_formatter.rb
 - lib/jsduck/class_writer.rb
+- lib/jsduck/css_lexer.rb
 - lib/jsduck/css_parser.rb
 - lib/jsduck/doc_formatter.rb
 - lib/jsduck/doc_parser.rb