jsduck 0.5 → 0.6

data/lib/jsduck/doc_formatter.rb

@@ -1,17 +1,31 @@
 require 'rubygems'
 require 'rdiscount'
+require 'strscan'
+require 'cgi'
 
 module JsDuck
 
   # Formats doc-comments
   class DocFormatter
-    # CSS class to add to each link
-    attr_accessor :css_class
+    # Template HTML that replaces {@link Class#member anchor text}.
+    # Can contain placeholders:
+    #
+    # %c - full class name (e.g. "Ext.Panel")
+    # %m - class member name (e.g. "urlEncode")
+    # %M - class member name, prefixed with hash (e.g. "#urlEncode")
+    # %a - anchor text for link
+    #
+    # Default value: '<a href="%c%M">%a</a>'
+    attr_accessor :link_tpl
 
-    # Template for the href URL.
-    # Can contain %cls% which is replaced with actual classname.
-    # Also '#' and member name is appended to link if needed
-    attr_accessor :url_template
+    # Template HTML that replaces {@img URL alt text}
+    # Can contain placeholders:
+    #
+    # %u - URL from @img tag (e.g. "some/path.png")
+    # %a - alt text for image
+    #
+    # Default value: '<img src="%u" alt="%a"/>'
+    attr_accessor :img_tpl
 
     # Sets up instance to work in context of particular class, so
     # that when {@link #blah} is encountered it knows that
@@ -21,19 +35,53 @@ module JsDuck
     # Maximum length for text that doesn't get shortened, defaults to 120
     attr_accessor :max_length
 
+    # JsDuck::Relations for looking up class names.
+    #
+    # When auto-creating class links from CamelCased names found from
+    # text, we check the relations object to see if a class with that
+    # name actually exists.
+    attr_accessor :relations
+
     def initialize
       @context = ""
-      @css_class = nil
-      @url_template = "%cls%"
       @max_length = 120
+      @relations = {}
+      @link_tpl = '<a href="%c%M">%a</a>'
+      @img_tpl = '<img src="%u" alt="%a"/>'
+      @link_re = /\{@link\s+(\S*?)(?:\s+(.+?))?\}/m
+      @img_re = /\{@img\s+(\S*?)(?:\s+(.+?))?\}/m
     end
 
+    # Replaces {@link} and {@img} tags, auto-generates links for
+    # recognized classnames.
+    #
     # Replaces {@link Class#member link text} in given string with
-    # HTML links pointing to documentation.  In addition to the href
-    # attribute links will also contain ext:cls and ext:member
-    # attributes.
+    # HTML from @link_tpl.
+    #
+    # Replaces {@img path/to/image.jpg Alt text} with HTML from @img_tpl.
+    #
+    # Additionally replaces strings recognized as ClassNames with
+    # links to these classes.  So one doesn even need to use the @link
+    # tag to create a link.
     def replace(input)
-      input.gsub(/\{@link\s+(\S*?)(?:\s+(.+?))?\}/m) do
+      s = StringScanner.new(input)
+      out = ""
+      while !s.eos? do
+        if s.check(@link_re)
+          out += replace_link_tag(s.scan(@link_re))
+        elsif s.check(@img_re)
+          out += replace_img_tag(s.scan(@img_re))
+        elsif s.check(/\{/)
+          out += s.scan(/\{/)
+        else
+          out += replace_class_names(s.scan(/[^{]+/))
+        end
+      end
+      out
+    end
+
+    def replace_link_tag(input)
+      input.sub(@link_re) do
         target = $1
         text = $2
         if target =~ /^(.*)#(.*)$/
@@ -57,14 +105,57 @@ module JsDuck
       end
     end
 
-    # Creates HTML link to class and/or member
-    def link(cls, member, label)
-      anchor = member ? "#" + member : ""
-      url = @url_template.sub(/%cls%/, cls) + anchor
-      href = ' href="' + url + '"'
-      rel = ' rel="' + cls + anchor + '"'
-      cssCls = @css_class ? ' class="' + @css_class + '"' : ''
-      "<a" + href + rel + cssCls + ">" + label + "</a>"
+    def replace_img_tag(input)
+      input.sub(@img_re) { img($1, $2) }
+    end
+
+    def replace_class_names(input)
+      input.gsub(/(\A|\s)([A-Z][A-Za-z0-9.]*[A-Za-z0-9])(?:(#)([A-Za-z0-9]+))?([.,]?(?:\s|\Z))/m) do
+        before = $1
+        cls = $2
+        hash = $3
+        method = $4
+        after = $5
+
+        if @relations[cls]
+          label = method ? cls+"."+method : cls
+          before + link(cls, method, label) + after
+        else
+          before + cls + (hash || "") + (method || "") + after
+        end
+      end
+    end
+
+    # applies the image template
+    def img(url, alt_text)
+      @img_tpl.gsub(/(%\w)/) do
+        case $1
+        when '%u'
+          url
+        when '%a'
+          CGI.escapeHTML(alt_text||"")
+        else
+          $1
+        end
+      end
+    end
+
+    # applies the link template
+    def link(cls, member, anchor_text)
+      @link_tpl.gsub(/(%\w)/) do
+        case $1
+        when '%c'
+          cls
+        when '%m'
+          member ? member : ""
+        when '%M'
+          member ? "#"+member : ""
+        when '%a'
+          CGI.escapeHTML(anchor_text||"")
+        else
+          $1
+        end
+      end
     end
 
     # Formats doc-comment for placement into HTML.

data/lib/jsduck/doc_parser.rb

@@ -21,6 +21,11 @@ module JsDuck
   # @see and {@link} are parsed separately in JsDuck::DocFormatter.
   #
   class DocParser
+    # Pass in :css to be able to parse CSS doc-comments
+    def initialize(mode = :js)
+      @ident_pattern = (mode == :css) ? /\$[a-zA-Z0-9_-]*/ : /\w+/
+    end
+
     def parse(input)
       @tags = []
       @input = StringScanner.new(purify(input))
@@ -66,8 +71,12 @@ module JsDuck
       while !@input.eos? do
         if look(/@class\b/)
           at_class
-        elsif look(/@extends\b/)
+        elsif look(/@extends?\b/)
           at_extends
+        elsif look(/@mixins?\b/)
+          at_mixins
+        elsif look(/@alternateClassNames?\b/)
+          at_alternateClassName
         elsif look(/@singleton\b/)
           boolean_at_tag(/@singleton/, :singleton)
         elsif look(/@event\b/)
@@ -92,6 +101,10 @@ module JsDuck
           at_member
         elsif look(/@author\b/)
           at_author
+        elsif look(/@docauthor\b/)
+          at_docauthor
+        elsif look(/@var\b/)
+          at_var
         elsif look(/@static\b/)
           boolean_at_tag(/@static/, :static)
         elsif look(/@(private|ignore|hide|protected)\b/)
@@ -117,12 +130,30 @@ module JsDuck
 
     # matches @extends name ...
     def at_extends
-      match(/@extends/)
+      match(/@extends?/)
       add_tag(:extends)
       maybe_ident_chain(:extends)
       skip_white
     end
 
+    # matches @mixins name1 name2 ...
+    def at_mixins
+      match(/@mixins?/)
+      add_tag(:mixins)
+      skip_horiz_white
+      @current_tag[:mixins] = class_list
+      skip_white
+    end
+
+    # matches @alternateClassName name1 name2 ...
+    def at_alternateClassName
+      match(/@alternateClassNames?/)
+      add_tag(:alternateClassNames)
+      skip_horiz_white
+      @current_tag[:alternateClassNames] = class_list
+      skip_white
+    end
+
     # matches @event name ...
     def at_event
       match(/@event/)
@@ -179,6 +210,15 @@ module JsDuck
       skip_white
     end
 
+    # matches @var {type} $name ...
+    def at_var
+      match(/@var/)
+      add_tag(:css_var)
+      maybe_type
+      maybe_name
+      skip_white
+    end
+
     # matches @type {type}  or  @type type
     #
     # The presence of @type implies that we are dealing with property.
@@ -221,6 +261,15 @@ module JsDuck
       skip_white
     end
 
+    # matches @docauthor some name ... newline
+    def at_docauthor
+      match(/@docauthor/)
+      add_tag(:docauthor)
+      skip_horiz_white
+      @current_tag[:name] = @input.scan(/.*$/)
+      skip_white
+    end
+
     # Used to match @private, @ignore, @hide, ...
     def boolean_at_tag(regex, propname)
       match(regex)
@@ -239,8 +288,8 @@ module JsDuck
     # matches identifier name if possible and sets it on @current_tag
     def maybe_name
       skip_horiz_white
-      if look(/\w/)
-        @current_tag[:name] = ident
+      if look(@ident_pattern)
+        @current_tag[:name] = @input.scan(@ident_pattern)
       end
     end
 
@@ -260,6 +309,17 @@ module JsDuck
       return name
     end
 
+    # matches <ident_chain> <ident_chain> ... until line end
+    def class_list
+      skip_horiz_white
+      classes = []
+      while look(/\w/)
+        classes << ident_chain
+        skip_horiz_white
+      end
+      classes
+    end
+
     # matches chained.identifier.name and returns it
     def ident_chain
       @input.scan(/[\w.]+/)

data/lib/jsduck/event_table.rb

@@ -5,15 +5,15 @@ require 'jsduck/long_params'
 module JsDuck
 
   class EventTable < Table
-    def initialize(cls, cache={})
-      super(cls, cache)
+    def initialize(cls, formatter, cache={})
+      super(cls, formatter, cache)
       @type = :event
       @id = @cls.full_name + "-events"
       @title = "Public Events"
       @column_title = "Event"
       @row_class = "event-row"
       @short_params = ShortParams.new
-      @long_params = LongParams.new(@cls)
+      @long_params = LongParams.new(@formatter)
     end
 
     def signature_suffix(item)

data/lib/jsduck/exporter.rb

@@ -9,29 +9,31 @@ module JsDuck
   # Also all the :doc elements will be formatted - converted from
   # markdown to HTML and @links resolved.
   class Exporter
-    attr_accessor :relations
-
-    def initialize(relations)
+    def initialize(relations, formatter)
       @relations = relations
-      @formatter = DocFormatter.new
-      @formatter.css_class = 'docClass'
+      @formatter = formatter
     end
 
     # Returns all data in Class object as hash.
     def export(cls)
       h = cls.to_hash
       h[:cfgs] = cls.members(:cfg)
-      h[:properties] = cls.members(:property)
-      h[:methods] = cls.members(:method)
-      h[:events] = cls.members(:event)
       h.delete(:cfg)
+      h[:properties] = cls.members(:property)
       h.delete(:property)
+      h[:methods] = cls.members(:method)
       h.delete(:method)
+      h[:events] = cls.members(:event)
       h.delete(:event)
+      h[:cssVars] = cls.members(:css_var)
+      h.delete(:css_var)
+      h[:cssMixins] = cls.members(:css_mixin)
+      h.delete(:css_mixin)
       h[:component] = cls.inherits_from?("Ext.Component")
       h[:superclasses] = cls.superclasses.collect {|c| c.full_name }
       h[:subclasses] = @relations.subclasses(cls).collect {|c| c.full_name }
       h[:mixedInto] = @relations.mixed_into(cls).collect {|c| c.full_name }
+      h[:allMixins] = cls.all_mixins.collect {|c| c.full_name }
       format_class(h)
     end
 
@@ -39,7 +41,7 @@ module JsDuck
     def format_class(c)
       @formatter.context = c[:name]
       c[:doc] = @formatter.format(c[:doc]) if c[:doc]
-      [:cfgs, :properties, :methods, :events].each do |type|
+      [:cfgs, :properties, :methods, :events, :cssVars, :cssMixins].each do |type|
         c[type] = c[type].map {|m| format_member(m) }
       end
       c

data/lib/jsduck/inheritance_tree.rb

@@ -1,15 +1,10 @@
-require 'jsduck/doc_formatter'
-
 module JsDuck
 
   # Creates the inheritance tree shown on class documentation page.
   class InheritanceTree
-    def initialize(cls)
+    def initialize(cls, formatter)
       @cls = cls
-      @formatter = DocFormatter.new
-      @formatter.context = cls.full_name
-      @formatter.css_class = 'docClass'
-      @formatter.url_template = 'output/%cls%.html'
+      @formatter = formatter
     end
 
     # Renders the tree using HTML <pre> element

data/lib/jsduck/{parser.rb → js_parser.rb}

@@ -3,7 +3,7 @@ require 'jsduck/doc_parser'
 
 module JsDuck
 
-  class Parser
+  class JsParser
     def initialize(input)
       @lex = Lexer.new(input)
       @doc_parser = DocParser.new
@@ -195,7 +195,7 @@ module JsDuck
       cfg
     end
 
-    # <ext-define-cfg> := "{" ( <extend> | <mixins> | <?> )*
+    # <ext-define-cfg> := "{" ( <extend> | <mixins> | <alternate-class-name> | <?> )*
     def ext_define_cfg
       match("{")
       cfg = {}
@@ -208,6 +208,9 @@ module JsDuck
         elsif look("mixins", ":", "{")
           cfg[:mixins] = ext_define_mixins
           found = true
+        elsif look("alternateClassName", ":")
+          cfg[:alternateClassNames] = ext_define_alternate_class_name
+          found = true
         elsif look(:ident, ":")
           match(:ident, ":")
           if look(:string) || look(:number) || look(:regex) ||
@@ -231,6 +234,18 @@ module JsDuck
       match("extend", ":", :string)
     end
 
+    # <ext-define-alternate-class-name> := "alternateClassName" ":" ( <string> | <array-of-strings> )
+    def ext_define_alternate_class_name
+      match("alternateClassName", ":")
+      if look(:string)
+        [ match(:string) ]
+      elsif look("[")
+        array_of_strings
+      else
+        []
+      end
+    end
+
     # <ext-define-mixins> := "mixins" ":" "{" [ <ident> ":" <string> ","? ]* "}"
     def ext_define_mixins
       match("mixins", ":", "{")
@@ -246,14 +261,15 @@ module JsDuck
     # <array-of-strings> := "[" [ <string> ","? ]* "]"
     def array_of_strings
       match("[")
+      strs = []
       while look(:string)
-        match(:string)
+        strs << match(:string)
         match(",") if look(",")
       end
 
       if look("]")
         match("]")
-        true
+        strs
       else
         false
       end

data/lib/jsduck/lexer.rb

@@ -135,8 +135,7 @@ module JsDuck
           nr = @input.scan(/[0-9]+(\.[0-9]*)?/)
           @tokens << {
             :type => :number,
-            # When number ends with ".", append "0" so Ruby eval will work
-            :value => eval(/\.$/ =~ nr ? nr+"0" : nr)
+            :value => nr
           }
         elsif @input.check(/\$/)
           value = @input.scan(/\$\w*/)