jsduck 3.0.pre2 → 3.0.pre3

data/lib/jsduck/doc_formatter.rb

@@ -29,9 +29,12 @@ module JsDuck
     # Default value: '<img src="%u" alt="%a"/>'
     attr_accessor :img_tpl
 
-    # Assign to this a function that retrieves the example code when
-    # passed in a filename
-    attr_accessor :get_example
+    # This will hold list of all image paths gathered from {@img} tags.
+    attr_accessor :images
+
+    # Base path to prefix images from {@img} tags.
+    # Defaults to no prefix.
+    attr_accessor :img_path
 
     # Sets up instance to work in context of particular class, so
     # that when {@link #blah} is encountered it knows that
@@ -57,13 +60,12 @@ module JsDuck
       @doc_context = {}
       @max_length = 120
       @relations = {}
+      @images = []
       @link_tpl = '<a href="%c%#%m">%a</a>'
       @img_tpl = '<img src="%u" alt="%a"/>'
-      @example_tpl = '<pre class="inline-example"><code>%a</code></pre>'
       @link_re = /\{@link\s+(\S*?)(?:\s+(.+?))?\}/m
       @img_re = /\{@img\s+(\S*?)(?:\s+(.+?))?\}/m
-      @example_re = /\{@example\s+(\S*?)\s*\}/m
-      @example_annotation_re = /<pre><code>@example( +[^\n]*)?\s+/m
+      @example_annotation_re = /<pre><code>\s*@example( +[^\n]*)?\s+/m
     end
 
     # Replaces {@link} and {@img} tags, auto-generates links for
@@ -74,8 +76,6 @@ module JsDuck
     #
     # Replaces {@img path/to/image.jpg Alt text} with HTML from @img_tpl.
     #
-    # Replaces {@example path/to/example.js} with source from that file.
-    #
     # Adds 'inline-example' class to code examples beginning with @example.
     #
     # Additionally replaces strings recognized as ClassNames with
@@ -89,11 +89,12 @@ module JsDuck
           out += replace_link_tag(s.scan(@link_re))
         elsif s.check(@img_re)
           out += replace_img_tag(s.scan(@img_re))
-        elsif s.check(@example_re)
-          out += replace_example_tag(s.scan(@example_re))
         elsif s.check(@example_annotation_re)
-          s.scan(@example_annotation_re)
-          out += '<pre class="inline-example"><code>'
+          # Match possible classnames following @example and add them
+          # as CSS classes inside <pre> element.
+          s.scan(@example_annotation_re) =~ @example_annotation_re
+          css_classes = ($1 || "").strip
+          out += "<pre class='inline-example #{css_classes}'><code>"
         elsif s.check(/[{<]/)
           out += s.scan(/[{<]/)
         else
@@ -129,10 +130,10 @@ module JsDuck
         file = @doc_context[:filename]
         line = @doc_context[:linenr]
         if !@relations[cls]
-          Logger.instance.warn("#{file} line #{line} #{input} links to non-existing class.")
+          Logger.instance.warn("#{input} links to non-existing class", file, line)
           text
         elsif member && !get_member(cls, member, type)
-          Logger.instance.warn("#{file} line #{line} #{input} links to non-existing member.")
+          Logger.instance.warn("#{input} links to non-existing member", file, line)
           text
         else
           link(cls, member, text, type)
@@ -144,10 +145,6 @@ module JsDuck
       input.sub(@img_re) { img($1, $2) }
     end
 
-    def replace_example_tag(input)
-      input.sub(@example_re) { example($1) }
-    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
@@ -167,10 +164,11 @@ module JsDuck
 
     # applies the image template
     def img(url, alt_text)
+      @images << url
       @img_tpl.gsub(/(%\w)/) do
         case $1
         when '%u'
-          url
+          @img_path ? (@img_path + "/" + url) : url
         when '%a'
           CGI.escapeHTML(alt_text||"")
         else
@@ -179,24 +177,6 @@ module JsDuck
       end
     end
 
-    # Replaces example template with example read from file
-    def example(path)
-      @example_tpl.gsub(/(%\w)/) do
-        case $1
-        when '%a'
-          if @get_example
-            CGI.escapeHTML(@get_example.call(path))
-          else
-            file = @doc_context[:filename]
-            line = @doc_context[:linenr]
-            Logger.instance.warn("--examples not specified, but {@example} found in #{file} line #{line}.")
-          end
-        else
-          $1
-        end
-      end
-    end
-
     # applies the link template
     def link(cls, member, anchor_text, type=nil)
       # Use the canonical class name for link (not some alternateClassName)

data/lib/jsduck/doc_parser.rb

@@ -30,7 +30,7 @@ module JsDuck
 
       @meta_tags_map = {}
       (meta_tags || []).each do |tag|
-        @meta_tags_map[tag[:name]] = true
+        @meta_tags_map[tag.name] = tag
       end
     end
 
@@ -136,6 +136,8 @@ module JsDuck
           boolean_at_tag(/@protected/, :protected)
         elsif look(/@accessor\b/)
           boolean_at_tag(/@accessor/, :accessor)
+        elsif look(/@evented\b/)
+          boolean_at_tag(/@evented/, :evented)
         elsif look(/@template\b/)
           boolean_at_tag(/@template/, :template)
         elsif look(/@markdown\b/)
@@ -146,12 +148,9 @@ module JsDuck
           boolean_at_tag(/@abstract/, :abstract)
         elsif look(/@/)
           @input.scan(/@/)
-          if @meta_tags_map[look(/\w+/)]
-            add_tag(:meta)
-            @current_tag[:name] = match(/\w+/)
-            skip_horiz_white
-            @current_tag[:content] = @input.scan(/.*$/)
-            skip_white
+          tag = @meta_tags_map[look(/\w+/)]
+          if tag
+            meta_at_tag(tag)
           else
             @current_tag[:doc] += "@"
           end
@@ -161,6 +160,24 @@ module JsDuck
       end
     end
 
+    # Matches the given meta-tag
+    def meta_at_tag(tag)
+      prev_tag = @current_tag
+
+      add_tag(:meta)
+      @current_tag[:name] = match(/\w+/)
+      skip_horiz_white
+
+      # Fors singleline tags, scan to the end of line and finish the
+      # tag.  For multiline tags we leave the tag open for :doc
+      # addition just like with built-in multiline tags.
+      unless tag.multiline
+        @current_tag[:doc] = @input.scan(/.*$/).strip
+        skip_white
+        @current_tag = prev_tag
+      end
+    end
+
     # matches @class name ...
     def at_class
       match(/@class/)
@@ -354,7 +371,7 @@ module JsDuck
       end
     end
 
-    # matches: <ident-chain> | "[" <ident-chain> [ "=" <literal> ] "]"
+    # matches: <ident-chain> | "[" <ident-chain> [ "=" <default-value> ] "]"
     def maybe_name_with_default
       skip_horiz_white
       if look(/\[/)
@@ -364,7 +381,7 @@ module JsDuck
         if look(/=/)
           match(/=/)
           skip_horiz_white
-          @current_tag[:default] = literal
+          @current_tag[:default] = default_value
         end
         skip_horiz_white
         match(/\]/)
@@ -408,9 +425,20 @@ module JsDuck
       end
     end
 
-    def literal
+    # attempts to match javascript literal,
+    # when it fails grabs anything up to closing "]"
+    def default_value
+      start_pos = @input.pos
       lit = JsLiteralParser.new(@input).literal
-      lit ? JsLiteralBuilder.new.to_s(lit) : nil
+      if lit && look(/ *\]/)
+        # When lital matched and there's nothing after it up to the closing "]"
+        JsLiteralBuilder.new.to_s(lit)
+      else
+        # Otherwise reset parsing position to where we started
+        # and rescan up to "]" using simple regex.
+        @input.pos = start_pos
+        match(/[^\]]*/)
+      end
     end
 
     # matches {...} and returns text inside brackets

data/lib/jsduck/exporter.rb

@@ -29,6 +29,7 @@ module JsDuck
       cls.delete(:doc)
       cls[:members] = compact_members_group(cls[:members])
       cls[:statics] = compact_members_group(cls[:statics])
+      cls[:files] = compact_files(cls[:files])
       cls
     end
 
@@ -47,6 +48,16 @@ module JsDuck
       end
       m_copy
     end
+
+    # Remove full path from filename for privacy considerations as the
+    # path can reveal information about the system where JSDuck was
+    # run.  The docs app doesn't need to have this information.
+    def compact_files(files)
+      files.map do |f|
+        {:filename => File.basename(f[:filename]), :href => f[:href]}
+      end
+    end
+
   end
 
 end

data/lib/jsduck/guides.rb

@@ -44,14 +44,14 @@ module JsDuck
       guide_file = in_dir + "/README.md"
       return Logger.instance.warn("README.md not found in #{in_dir}") unless File.exists?(guide_file)
 
-      Logger.instance.log("Writing guide #{out_dir} ...")
+      Logger.instance.log("Writing guide", out_dir)
       # Copy the whole guide dir over
       FileUtils.cp_r(in_dir, out_dir)
 
       @formatter.doc_context = {:filename => guide_file, :linenr => 0}
-      html = @formatter.format(IO.read(guide_file))
       name = File.basename(in_dir)
-      html.gsub!(/<img src="/, "<img src=\"guides/#{name}/")
+      @formatter.img_path = "guides/#{name}"
+      html = @formatter.format(IO.read(guide_file))
 
       JsonDuck.write_jsonp(out_dir+"/README.js", name, {:guide => html, :title => guide["title"]})
     end

data/lib/jsduck/images.rb

@@ -0,0 +1,72 @@
+require "jsduck/logger"
+require "fileutils"
+
+module JsDuck
+
+  # Looks up images from directories specified through --images option.
+  class Images
+    def initialize(paths)
+      @paths = scan_for_images(paths)
+      @images = {}
+    end
+
+    # Scans each path for image files, building a hash of paths where
+    # each path points to a hash of image files found in that path.
+    def scan_for_images(paths)
+      map = {}
+      paths.each do |path|
+        # Scans directory for image files
+        map[path] = {}
+        Dir[path+"/**/*.{png,jpg,jpeg,gif}"].each do |img|
+          map[path][img] = false
+        end
+      end
+      map
+    end
+
+    # Adds relative image path of an image
+    def add(filename)
+      unless @images[filename]
+        @images[filename] = true
+      end
+    end
+
+    # Copys over images to given output dir
+    def copy(output_dir)
+      @images.each_key do |img|
+        unless copy_img(img, output_dir)
+          Logger.instance.warn("Image not found.", img)
+        end
+      end
+      report_unused
+    end
+
+    # Attempts to copy one image, returns true on success
+    def copy_img(img, output_dir)
+      @paths.each_pair do |path, map|
+        filename = path + "/" + img
+        if map.has_key?(filename)
+          dest = output_dir + "/" + img
+          Logger.instance.log("Copying image", dest)
+          FileUtils.makedirs(File.dirname(dest))
+          FileUtils.cp(filename, dest)
+          # mark file as used.
+          map[filename] = true
+          return true
+        end
+      end
+      return false
+    end
+
+    # Report unused images
+    def report_unused
+      @paths.each_pair do |path, map|
+        map.each_pair do |img, used|
+          Logger.instance.warn("Image not used.", img) unless used
+        end
+      end
+    end
+
+  end
+
+end

data/lib/jsduck/js_parser.rb

@@ -234,7 +234,7 @@ module JsDuck
     end
 
     # <ext-define-cfg> := "{" ( <extend> | <mixins> | <alternate-class-name> | <alias> |
-    #                           <requires> | <uses> | <singleton> | <?> )*
+    #                           <xtype> | <requires> | <uses> | <singleton> | <?> )*
     def ext_define_cfg
       match("{")
       cfg = {}
@@ -249,6 +249,8 @@ module JsDuck
           cfg[:alternateClassNames] = found
         elsif found = ext_define_alias
           cfg[:alias] = found
+        elsif found = ext_define_xtype
+          cfg[:xtype] = found
         elsif found = ext_define_requires
           cfg[:requires] = found
         elsif found = ext_define_uses
@@ -270,12 +272,18 @@ module JsDuck
       end
     end
 
-    # <mixins> := "mixins" ":" <object-literal>
+    # <mixins> := "mixins" ":" [ <object-literal> | <array-literal> ]
     def ext_define_mixins
-      if look("mixins", ":", "{")
+      if look("mixins", ":")
         match("mixins", ":")
         lit = literal
-        lit && lit[:value].map {|x| x[:value][:value] }
+        if lit && lit[:type] == :object
+          lit[:value].map {|x| x[:value][:value] }
+        elsif lit && lit[:type] == :array
+          lit[:value].map {|x| x[:value] }
+        else
+          nil
+        end
       end
     end
 
@@ -295,6 +303,14 @@ module JsDuck
       end
     end
 
+    # <xtype> := "xtype" ":" <string-or-list>
+    def ext_define_xtype
+      if look("xtype", ":")
+        match("xtype", ":")
+        string_or_list
+      end
+    end
+
     # <requires> := "requires" ":" <string-or-list>
     def ext_define_requires
       if look("requires", ":")

data/lib/jsduck/lexer.rb

@@ -118,8 +118,8 @@ module JsDuck
             :type => :operator,
             :value => @input.scan(/./)
           }
-        elsif @input.check(/[a-zA-Z_]/)
-          value = @input.scan(/\w+/)
+        elsif @input.check(/[a-zA-Z_$]/)
+          value = @input.scan(/[$\w]+/)
           return {
             :type => KEYWORDS[value] ? :keyword : :ident,
             :value => value
@@ -167,12 +167,6 @@ module JsDuck
             :type => :number,
             :value => nr
           }
-        elsif @input.check(/\$/)
-          value = @input.scan(/\$\w*/)
-          return {
-            :type => :ident,
-            :value => value
-          }
         elsif  @input.check(/./)
           return {
             :type => :operator,

data/lib/jsduck/lint.rb

@@ -75,8 +75,9 @@ module JsDuck
     end
 
     # Prints warning + filename and linenumber from doc-context
-    def warn(msg, context)
-      Logger.instance.warn(msg + " in #{context[:filename]} line #{context[:linenr]}")
+    def warn(msg, member)
+      context = member[:files][0]
+      Logger.instance.warn(msg, context[:filename], context[:linenr])
     end
 
   end

data/lib/jsduck/logger.rb

@@ -1,4 +1,5 @@
 require 'singleton'
+require 'jsduck/os'
 
 module JsDuck
 
@@ -15,9 +16,11 @@ module JsDuck
       @shown_warnings = {}
     end
 
-    # Prints log message
-    def log(msg)
-      puts msg if @verbose
+    # Prints log message with optional filename appended
+    def log(msg, filename=nil)
+      if @verbose
+        puts msg + " " + format(filename) + "..."
+      end
     end
 
     # Prints warning message.
@@ -25,12 +28,28 @@ module JsDuck
     # Ignores duplicate warnings - only prints the first one.
     # Works best when --processes=0, but it reduces the amount of
     # warnings greatly also when run multiple processes.
-    def warn(msg)
+    #
+    # Optionally filename and line number will be inserted to message.
+    def warn(msg, filename=nil, line=nil)
+      msg = "Warning: " + format(filename, line) + " " + msg
+
       if @warnings && !@shown_warnings[msg]
-        $stderr.puts "Warning: " + msg
+        $stderr.puts msg
         @shown_warnings[msg] = true
       end
     end
+
+    # Formats filename and line number for output
+    def format(filename=nil, line=nil)
+      out = ""
+      if filename
+        out = OS::windows? ? filename.gsub('/', '\\') : filename
+        if line
+          out += ":#{line}:"
+        end
+      end
+      out
+    end
   end
 
 end

data/lib/jsduck/merger.rb

@@ -1,3 +1,5 @@
+require 'jsduck/logger'
+
 module JsDuck
 
   # Takes data from doc-comment and code that follows it and combines
@@ -6,6 +8,15 @@ module JsDuck
   #
   # The main method merge() produces a hash as a result.
   class Merger
+    # Allow passing in filename and line for error reporting
+    attr_accessor :filename
+    attr_accessor :linenr
+
+    def initialize
+      @filename = ""
+      @linenr = 0
+    end
+
     def merge(docs, code)
       case detect_doc_type(docs, code)
       when :class
@@ -170,6 +181,7 @@ module JsDuck
         :default => detect_default(:cfg, doc_map, code),
         :properties => detect_subproperties(docs, :cfg),
         :accessor => !!doc_map[:accessor],
+        :evented => !!doc_map[:evented],
       }, doc_map)
     end
 
@@ -222,7 +234,9 @@ module JsDuck
     end
 
     def create_member_id(m)
-      "#{m[:static] ? 'static-' : ''}#{m[:tagname]}-#{m[:name]}"
+      # Sanitize $ in member names with something safer
+      name = m[:name].gsub(/\$/, 'S-')
+      "#{m[:static] ? 'static-' : ''}#{m[:tagname]}-#{name}"
     end
 
     def detect_name(tagname, doc_map, code, name_type = :last_name)
@@ -319,10 +333,17 @@ module JsDuck
     def detect_xtypes(doc_map, code)
       if doc_map[:xtype]
         {"widget" => doc_map[:xtype].map {|tag| tag[:name] } }
-      elsif code[:alias]
+      elsif code[:xtype] || code[:alias]
         xtypes = {}
-        code[:alias].each do |a|
-          if a =~ /^(\w+)\.(\w+)$/
+        (code[:xtype] || []).each do |a|
+          if xtypes["widget"]
+            xtypes["widget"] << a
+          else
+            xtypes["widget"] = [a]
+          end
+        end
+        (code[:alias] || []).each do |a|
+          if a =~ /^([\w.]+)\.(\w+)$/
             if xtypes[$1]
               xtypes[$1] << $2
             else
@@ -337,7 +358,12 @@ module JsDuck
     end
 
     def detect_meta(doc_map)
-      doc_map[:meta] ? doc_map[:meta].map {|tag| {:name => tag[:name], :content => tag[:content]} } : []
+      meta = {}
+      (doc_map[:meta] || []).map do |tag|
+        meta[tag[:name]] = [] unless meta[tag[:name]]
+        meta[tag[:name]] << tag[:doc]
+      end
+      meta
     end
 
     def detect_deprecated(doc_map)
@@ -407,8 +433,12 @@ module JsDuck
         if it[:name] =~ /^(.+)\.([^.]+)$/
           it[:name] = $2
           parent = index[$1]
-          parent[:properties] = [] unless parent[:properties]
-          parent[:properties] << it
+          if parent
+            parent[:properties] = [] unless parent[:properties]
+            parent[:properties] << it
+          else
+            Logger.instance.warn("Ignoring subproperty #{$1}.#{$2}, no parent found with name '#{$1}'.", @filename, @linenr)
+          end
         else
           items << it
         end
@@ -429,7 +459,7 @@ module JsDuck
     # Combines :doc-s of most tags
     # Ignores tags that have doc comment themselves and subproperty tags
     def detect_doc(docs)
-      ignore_tags = [:param, :return]
+      ignore_tags = [:param, :return, :meta]
       doc_tags = docs.find_all { |tag| !ignore_tags.include?(tag[:tagname]) && !subproperty?(tag) }
       doc_tags.map { |tag| tag[:doc] }.compact.join(" ")
     end

data/lib/jsduck/meta_tag.rb

@@ -0,0 +1,49 @@
+module JsDuck
+
+  # Abstract base class for all meta tag implementations.
+  #
+  # Child classes must define value for @name attribute.  They can
+  # also provide @multiline, and override #to_html method.
+  class MetaTag
+    # Name of the tag (required)
+    attr_reader :name
+
+    # True to include all lines up to next @tag as part of this meta-tag
+    attr_reader :multiline
+
+    # Override this to transform the content of meta-tag to HTML to be
+    # included into documentation.
+    #
+    # It gets passed an array of contents gathered from all meta-tags
+    # of given type. It should return an HTML string to inject into
+    # document.  For help in that it can use the #format method to
+    # easily support Markdown and {@link/img} tags inside the contents
+    # of meta-tag.
+    #
+    # By default the method returns nil, which means the tag will not
+    # be rendered at all.
+    def to_html(contents)
+    end
+
+    # This is used to inject the formatter object for #markdown method
+    attr_accessor :formatter
+
+    # Helper method to format the text in standard JsDuck way.
+    # This means running it through Markdown engine and expanding
+    # {@link} and {@img} tags.
+    def format(text)
+      @formatter.format(text)
+    end
+
+    # Returns all descendants of MetaTag class.
+    def self.descendants
+      result = []
+      ObjectSpace.each_object(::Class) do |cls|
+        result << cls if cls < self
+      end
+      result
+    end
+
+  end
+
+end

data/lib/jsduck/meta_tag_loader.rb

@@ -0,0 +1,48 @@
+require "jsduck/meta_tag"
+require 'jsduck/author_tag'
+require 'jsduck/doc_author_tag'
+
+module JsDuck
+
+  # Loads user-defined meta-tags
+  class MetaTagLoader
+    # instatiates builtin meta tags
+    def initialize
+      @classes = MetaTag.descendants
+      @meta_tags = @classes.map {|cls| cls.new }
+    end
+
+    # Loads user-defined meta-tags from given paths.
+    # Returns list of meta-tag instances.
+    def load(paths)
+      paths.each do |path|
+        if File.directory?(path)
+          Dir[path+"/**/*.rb"].each do |file|
+            require(file)
+            init_remaining
+          end
+        else
+          require(path)
+          init_remaining
+        end
+      end
+      @meta_tags
+    end
+
+    # Instantiates meta tag classes that haven't been instantiated
+    # already. This is called after each meta-tags file is loaded so
+    # that the list of meta-tags will be in order specified from
+    # command line.
+    def init_remaining
+      MetaTag.descendants.each do |cls|
+        if !@classes.include?(cls)
+          @classes << cls
+          newtag = cls.new
+          @meta_tags = @meta_tags.find_all {|t| t.name != newtag.name }
+          @meta_tags << newtag
+        end
+      end
+    end
+  end
+
+end