jsduck 4.5.1 → 4.6.0

data/README.md

@@ -64,7 +64,7 @@ most sensible place to put it). Now you're ready to install JSDuck:
     > gem install jsduck
 
 [RVM]: https://rvm.io/
-[download page]: https://github.com/senchalabs/jsduck/downloads
+[download page]: https://sourceforge.net/projects/jsduck/files/
 [libs download]: https://github.com/stereobooster/therubyracer/downloads
 
 Usage
@@ -172,6 +172,7 @@ Katherine Chu,
 [burnnat](https://github.com/burnnat),
 [vjetteam](https://github.com/vjetteam),
 [Chris Westbrook](https://github.com/cnstaging),
+[Scott Whittaker](https://github.com/scottrobertwhittaker),
 and many-many others who reported bugs, submitted patches, and
 provided a lot of useful input.
 

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)
 
@@ -257,8 +257,6 @@ task :sdk => :sass do
     "--output", OUT_DIR,
     "--config", "#{SDK_DIR}/extjs/docs/config.json",
     "--examples-base-url", "extjs-build/examples/",
-    "--import", "Ext 4.1.3:#{SDK_DIR}/../docs.sencha.com/exports/extjs-4.1.3",
-    "--import", "Ext 4.2.0",
     "--seo"
   )
   runner.add_debug

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.5.1'
-  s.date = '2012-12-07'
+  s.version = '4.6.0'
+  s.date = '2013-01-09'
   s.summary = "Simple JavaScript Duckumentation generator"
   s.description = "Documentation generator for Sencha JS frameworks"
   s.homepage = "https://github.com/senchalabs/jsduck"
@@ -22,7 +22,7 @@ Gem::Specification.new do |s|
   s.add_dependency 'rdiscount'
   s.add_dependency 'json'
   s.add_dependency 'parallel'
-  s.add_dependency 'therubyracer', '= 0.10.1'
+  s.add_dependency 'therubyracer', '>= 0.10.0', '< 0.11.0'
 
   s.add_development_dependency 'rspec'
   s.add_development_dependency 'rake'

data/lib/jsduck/batch_parser.rb

@@ -9,6 +9,7 @@ require 'jsduck/inherit_doc'
 require 'jsduck/importer'
 require 'jsduck/return_values'
 require 'jsduck/lint'
+require 'jsduck/circular_deps'
 
 module JsDuck
 
@@ -95,6 +96,7 @@ module JsDuck
 
     # Do all kinds of post-processing on relations.
     def apply_extra_processing
+      CircularDeps.new(@relations).check_all
       InheritDoc.new(@relations).resolve_all
       Importer.import(@opts.imports, @relations, @opts.new_since)
       ReturnValues.auto_detect(@relations)

data/lib/jsduck/circular_deps.rb

@@ -1,7 +1,24 @@
+require 'jsduck/logger'
+
 module JsDuck
 
   # Checks for circular dependencies
   class CircularDeps
+    def initialize(classes)
+      @classes = classes
+    end
+
+    # Checks all classes for circular dependencies.
+    #
+    # When found, exits with a fatal error message.
+    def check_all
+      @classes.each do |cls|
+        if chain = check(cls)
+          Logger.fatal("Class #{cls[:name]} has a circular dependency: #{chain}")
+          exit 1
+        end
+      end
+    end
 
     # Checks class for circular dependencies.
     #

data/lib/jsduck/class_formatter.rb

@@ -2,6 +2,7 @@ require 'jsduck/type_parser'
 require 'jsduck/logger'
 require 'jsduck/meta_tag_registry'
 require 'jsduck/shortener'
+require 'jsduck/util/html'
 
 module JsDuck
 
@@ -80,7 +81,7 @@ module JsDuck
         else
           Logger.warn(:type_name, "Unknown type #{type}", context[:filename], context[:linenr])
         end
-        type
+        Util::HTML.escape(type)
       end
     end
 

data/lib/jsduck/doc_ast.rb

@@ -257,9 +257,10 @@ module JsDuck
     end
 
     def detect_return(doc_map)
+      has_return_tag = !!extract(doc_map, :return)
       ret = extract(doc_map, :return) || {}
       return {
-        :type => ret[:type] || "undefined",
+        :type => ret[:type] || (has_return_tag ? "Object" : "undefined"),
         :name => ret[:name] || "return",
         :doc => ret[:doc] || "",
         :properties => doc_map[:return] ? detect_subproperties(:return, doc_map[:return]) : []

data/lib/jsduck/doc_formatter.rb

@@ -1,6 +1,7 @@
 require 'rubygems'
 require 'strscan'
 require 'rdiscount'
+require 'jsduck/html_stack'
 require 'jsduck/inline/link'
 require 'jsduck/inline/img'
 require 'jsduck/inline/video'
@@ -15,10 +16,12 @@ module JsDuck
     # command line.  For the actual effect of the options see
     # Inline::* classes.
     def initialize(opts={})
+      @opts = opts
       @inline_link = Inline::Link.new(opts)
       @inline_img = Inline::Img.new(opts)
       @inline_video = Inline::Video.new(opts)
       @inline_example = Inline::Example.new(opts)
+      @doc_context = {}
     end
 
     # Sets base path to prefix images from {@img} tags.
@@ -41,13 +44,14 @@ module JsDuck
     # Sets up instance to work in context of particular doc object.
     # Used for error reporting.
     def doc_context=(doc)
+      @doc_context = doc
       @inline_video.doc_context = doc
       @inline_link.doc_context = doc
     end
 
     # Returns the current documentation context
     def doc_context
-      @inline_link.doc_context
+      @doc_context
     end
 
     # JsDuck::Relations for looking up class names.
@@ -94,10 +98,10 @@ module JsDuck
       s = StringScanner.new(input)
       out = ""
 
-      # Keep track of the nesting level of <a> tags. We're not
-      # auto-detecting class names when inside <a>. Normally links
-      # shouldn't be nested, but just to be extra safe.
-      open_a_tags = 0
+      # Keep track of open HTML tags. We're not auto-detecting class
+      # names when inside <a>. Also we want to close down the unclosed
+      # tags.
+      tags = HtmlStack.new(@opts[:ignore_html] || {}, @doc_context)
 
       while !s.eos? do
         if substitute = @inline_link.replace(s)
@@ -111,26 +115,24 @@ module JsDuck
           out += s.scan(/[{]/)
         elsif substitute = @inline_example.replace(s)
           out += substitute
-        elsif s.check(/<a\b/)
-          # Increment number of open <a> tags.
-          open_a_tags += 1
-          out += s.scan_until(/>|\Z/)
-        elsif s.check(/<\/a>/)
-          # <a> closed, auto-detection may continue when no more <a> tags open.
-          open_a_tags -= 1
-          out += s.scan(/<\/a>/)
+        elsif s.check(/<\w/)
+          # Open HTML tag
+          out += s.scan(/</) + tags.open(s.scan(/\w+/)) + s.scan_until(/>|\Z/)
+        elsif s.check(/<\/\w+>/)
+          # Close HTML tag
+          out += s.scan(/<\//) + tags.close(s.scan(/\w+/)) + s.scan(/>/)
         elsif s.check(/</)
-          # Ignore all other HTML tags
-          out += s.scan_until(/>|\Z/)
+          # Ignore plain '<' char.
+          out += s.scan(/</)
         else
           # Replace class names in the following text up to next "<" or "{"
           # but only when we're not inside <a>...</a>
           text = s.scan(/[^{<]+/)
-          out += open_a_tags > 0 ? text : @inline_link.create_magic_links(text)
+          out += tags.open?("a") ? text : @inline_link.create_magic_links(text)
         end
       end
 
-      out
+      out + tags.close_unfinished
     end
 
     # Creates a link based on the link template.

data/lib/jsduck/doc_parser.rb

@@ -506,7 +506,7 @@ module JsDuck
     # roll back to beginning and simply grab anything up to closing "]".
     def default_value
       start_pos = @input.pos
-      value = parse_balanced(/\[/, /\]/, /[^\[\]]*/)
+      value = parse_balanced(/\[/, /\]/, /[^\[\]'"]*/)
       if look(/\]/)
         value
       else
@@ -519,7 +519,7 @@ module JsDuck
     def typedef
       match(/\{/)
 
-      name = parse_balanced(/\{/, /\}/, /[^{}]*/)
+      name = parse_balanced(/\{/, /\}/, /[^{}'"]*/)
 
       if name =~ /=$/
         name = name.chop
@@ -538,18 +538,37 @@ module JsDuck
     #
     # @param re_open  The beginning brace regex
     # @param re_close The closing brace regex
-    # @param re_rest  Regex to match text without any braces
+    # @param re_rest  Regex to match text without any braces and strings
     def parse_balanced(re_open, re_close, re_rest)
-      result = match(re_rest)
+      result = parse_with_strings(re_rest)
       while look(re_open)
         result += match(re_open)
         result += parse_balanced(re_open, re_close, re_rest)
         result += match(re_close)
+        result += parse_with_strings(re_rest)
+      end
+      result
+    end
+
+    # Helper for parse_balanced to parse rest of the text between
+    # braces, taking account the strings which might occur there.
+    def parse_with_strings(re_rest)
+      result = match(re_rest)
+      while look(/['"]/)
+        result += parse_string('"') if look(/"/)
+        result += parse_string("'") if look(/'/)
         result += match(re_rest)
       end
       result
     end
 
+    # Parses "..." or '...' including the escape sequence \' or '\"
+    def parse_string(quote)
+      re_quote = Regexp.new(quote)
+      re_rest = Regexp.new("(?:[^"+quote+"\\\\]|\\\\.)*")
+      match(re_quote) + match(re_rest) + (match(re_quote) || "")
+    end
+
     # matches <ident_chain> <ident_chain> ... until line end
     def class_list
       skip_horiz_white

data/lib/jsduck/guides.rb

@@ -59,8 +59,7 @@ module JsDuck
 
       begin
         @formatter.doc_context = {:filename => guide_file, :linenr => 0}
-        name = File.basename(guide["url"])
-        @formatter.img_path = "guides/#{name}"
+        @formatter.img_path = "guides/#{guide["name"]}"
 
         return add_toc(guide, @formatter.format(Util::IO.read(guide_file)))
       rescue

data/lib/jsduck/html_stack.rb

@@ -0,0 +1,91 @@
+require 'jsduck/logger'
+
+module JsDuck
+
+  # Tracks opening and closing of HTML tags, with the purpose of
+  # closing down the unfinished tags.
+  #
+  # Synopsis:
+  #
+  #     tags = HtmlStack.new
+  #     # open and close a bunch of tags
+  #     tags.open("a")
+  #     tags.open("b")
+  #     tags.close("b")
+  #
+  #     # ask which tags still need to be closed
+  #     tags.close_unfinished --> "</a>"
+  #
+  class HtmlStack
+
+    # Initializes the stack with two optional parameters:
+    #
+    # @param ignore_html A hash of additional HTML tags that don't need closing.
+    # @param doc_context Filename and linenr of the current doc-comment.
+    def initialize(ignore_html={}, doc_context={})
+      @ignore_html = ignore_html
+      @doc_context = doc_context
+      @open_tags = []
+    end
+
+    # Registers opening of a tag.  Returns the tag.
+    def open(tag)
+      @open_tags.unshift(tag) unless void?(tag)
+      tag
+    end
+
+    # Registers closing of a tag.  Returns the tag.
+    def close(tag)
+      if @open_tags.include?(tag)
+        # delete the most recent unclosed tag in our tags stack
+        @open_tags.delete_at(@open_tags.index(tag))
+      end
+      tag
+    end
+
+    # True when the tag is currently open.
+    def open?(tag)
+      @open_tags.include?(tag)
+    end
+
+    # Returns HTML for closing the still open tags.
+    # Also prints warnings for all the unclosed tags.
+    def close_unfinished
+      return "" if @open_tags.length == 0
+
+      warn_unfinished
+
+      @open_tags.map {|tag| "</#{tag}>" }.join
+    end
+
+    private
+
+    def warn_unfinished
+      ctx = @doc_context
+      tag_list = @open_tags.map {|tag| "<#{tag}>" }.join(", ")
+      Logger.warn(:html, "Unclosed HTML tag: #{tag_list}", ctx[:filename], ctx[:linenr])
+    end
+
+    def void?(tag)
+      VOID_TAGS[tag] || @ignore_html[tag]
+    end
+
+    # Tags that don't require closing
+    VOID_TAGS = {
+      "base" => true,
+      "link" => true,
+      "meta" => true,
+      "hr" => true,
+      "br" => true,
+      "wbr" => true,
+      "area" => true,
+      "img" => true,
+      "param" => true,
+      "input" => true,
+      "isindex" => true,
+      "option" => true,
+    }
+
+  end
+
+end

data/lib/jsduck/lint.rb

@@ -1,6 +1,5 @@
 require 'jsduck/logger'
 require 'jsduck/class'
-require 'jsduck/circular_deps'
 
 module JsDuck
 
@@ -21,7 +20,6 @@ module JsDuck
       warn_duplicate_members
       warn_singleton_statics
       warn_empty_enums
-      fail_on_circular_dependencies
     end
 
     # print warning for each member or parameter with no name
@@ -119,17 +117,6 @@ module JsDuck
       end
     end
 
-    # Print fatal error message for circular dependency.
-    def fail_on_circular_dependencies
-      circular_deps = CircularDeps.new
-      @relations.each do |cls|
-        if chain = circular_deps.check(cls)
-          Logger.fatal("Class #{cls[:name]} has a circular dependency: #{chain}")
-          exit 1
-        end
-      end
-    end
-
     # Loops through all members of all classes
     def each_member(&block)
       @relations.each {|cls| cls.all_local_members.each(&block) }

data/lib/jsduck/logger.rb

@@ -20,6 +20,7 @@ module JsDuck
         [:link, "{@link} to unknown class or member"],
         [:link_ambiguous, "{@link} is ambiguous"],
         [:link_auto, "Auto-detected link to unknown class or member"],
+        [:html, "Unclosed HTML tag."],
 
         [:alt_name, "Name used as both classname and alternate classname"],
         [:name_missing, "Member or parameter has no name"],

data/lib/jsduck/options.rb

@@ -39,6 +39,7 @@ module JsDuck
     attr_accessor :tests
     attr_accessor :comments_url
     attr_accessor :comments_domain
+    attr_accessor :ignore_html
 
     # Debugging
     attr_accessor :template_dir
@@ -90,7 +91,7 @@ module JsDuck
       @ext4_events = nil
       @meta_tag_paths = []
 
-      @version = "4.5.1"
+      @version = "4.6.0"
 
       # Customizing output
       @title = "Documentation - JSDuck"
@@ -116,6 +117,7 @@ module JsDuck
       @tests = false
       @comments_url = nil
       @comments_domain = nil
+      @ignore_html = {}
 
       # Debugging
       @root_dir = File.dirname(File.dirname(File.dirname(__FILE__)))
@@ -539,6 +541,21 @@ module JsDuck
           @touch_examples_ui = true
         end
 
+        opts.on('--ignore-html=TAG',
+          "Ignore a particular unclosed HTML tag.",
+          "",
+          "Normally all tags like <foo> that aren't followed at some",
+          "point with </foo> will get automatically closed by JSDuck",
+          "and a warning will be generated.  Except standard void tags",
+          "like <img> and <br>.  Use this option to specify additional",
+          "tags not requirering a closing tag.",
+          "",
+          "Useful for ignoring the ExtJS preprocessor directives",
+          "<locale> and <debug> which would otherwise be reported",
+          "as unclosed tags.") do |tag|
+          @ignore_html[tag] = true
+        end
+
         opts.separator ""
         opts.separator "Debugging:"
         opts.separator ""