jsduck 3.7.0 → 3.8.0

data/README.md

@@ -120,7 +120,9 @@ Thanks to [Ondřej Jirman](https://github.com/megous),
 [ligaard](https://github.com/ligaard),
 [Bill Hubbard](http://www.sencha.com/forum/member.php?272458-BillHubbard),
 [Ed Spencer](https://github.com/edspencer),
-[atian25](https://github.com/atian25) and many-many others who
+[atian25](https://github.com/atian25),
+Katherine Chu,
+[Rob Dougan](https://github.com/rdougan) and many-many others who
 reported bugs, submitted patches, and provided a lot of useful input.
 
 

data/Rakefile

@@ -13,7 +13,7 @@ end
 
 def load_sdk_vars
   if File.exists?("sdk-vars.rb")
-    require "sdk-vars.rb"
+    require "./sdk-vars.rb"
   else
     puts "Error: sdk-vars.rb not found."
     puts

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.7.0'
-  s.date = '2012-02-29'
+  s.version = '3.8.0'
+  s.date = '2012-03-15'
   s.summary = "Simple JavaScript Duckumentation generator"
   s.description = "Documentation generator for Sencha JS frameworks"
   s.homepage = "https://github.com/senchalabs/jsduck"

data/lib/jsduck/app.rb

@@ -10,6 +10,7 @@ require 'jsduck/parallel_wrap'
 require 'jsduck/logger'
 require 'jsduck/assets'
 require 'jsduck/json_duck'
+require 'jsduck/io'
 require 'jsduck/lint'
 require 'jsduck/template_dir'
 require 'jsduck/class_writer'
@@ -81,7 +82,7 @@ module JsDuck
     def parallel_parse(filenames)
       @parallel.map(filenames) do |fname|
         Logger.instance.log("Parsing", fname)
-        SourceFile.new(IO.read(fname), fname, @opts)
+        SourceFile.new(JsDuck::IO.read(fname), fname, @opts)
       end
     end
 

data/lib/jsduck/app_data.rb

@@ -22,7 +22,7 @@ module JsDuck
           :guides => @assets.guides.to_array,
           :videos => @assets.videos.to_array,
           :examples => @assets.examples.to_array,
-          :search => SearchData.new.create(@relations.classes),
+          :search => SearchData.new.create(@relations.classes, @assets),
           :stats => @opts.stats ? Stats.new.create(@relations.classes) : [],
           :signatures => MetaTagRegistry.instance.signatures,
           :localStorageDb => @opts.local_storage_db,

data/lib/jsduck/class.rb

@@ -178,7 +178,7 @@ module JsDuck
     end
 
     # merges second members hash into first one
-    def merge!(hash1, hash2)
+    def merge!(hash1, hash2, skip_overrides=false)
       hash2.each_pair do |name, m|
         if m[:meta] && m[:meta][:hide]
           if hash1[name]
@@ -210,7 +210,18 @@ module JsDuck
       # this, ignore overriding itself.
       if new[:owner] != old[:owner]
         new[:overrides] = [] unless new[:overrides]
-        new[:overrides] << old unless new[:overrides].any? {|m| m[:owner] == old[:owner] }
+        unless new[:overrides].any? {|m| m[:owner] == old[:owner] }
+          # Make a copy of the important properties for us.  We can't
+          # just push the actual `old` member itself, because there
+          # can be circular overrides (notably with Ext.Base), which
+          # will result in infinite loop when we try to convert our
+          # class into JSON.
+          new[:overrides] << {
+            :name => old[:name],
+            :owner => old[:owner],
+            :id => old[:id],
+          }
+        end
       end
     end
 

data/lib/jsduck/doc_formatter.rb

@@ -1,8 +1,11 @@
+# -*- coding: utf-8 -*-
 require 'rubygems'
 require 'rdiscount'
 require 'strscan'
 require 'cgi'
 require 'jsduck/logger'
+require 'jsduck/inline_img'
+require 'jsduck/inline_video'
 
 module JsDuck
 
@@ -20,22 +23,6 @@ module JsDuck
     # Default value: '<a href="%c%M">%a</a>'
     attr_accessor :link_tpl
 
-    # 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
-
-    # 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
     # Context#blah is meant.
@@ -61,13 +48,26 @@ module JsDuck
       @max_length = 120
       @relations = relations
       @images = []
+
+      @inline_img = InlineImg.new(opts)
+      @inline_video = InlineVideo.new(opts)
+
       @link_tpl = opts[:link_tpl] || '<a href="%c%#%m">%a</a>'
-      @img_tpl = opts[:img_tpl] || '<img src="%u" alt="%a"/>'
       @link_re = /\{@link\s+(\S*?)(?:\s+(.+?))?\}/m
-      @img_re = /\{@img\s+(\S*?)(?:\s+(.+?))?\}/m
+
       @example_annotation_re = /<pre><code>\s*@example( +[^\n]*)?\s+/m
     end
 
+    # Sets base path to prefix images from {@img} tags.
+    def img_path=(path)
+      @inline_img.base_path = path
+    end
+
+    # Returns list of all image paths gathered from {@img} tags.
+    def images
+      @inline_img.images
+    end
+
     # Replaces {@link} and {@img} tags, auto-generates links for
     # recognized classnames.
     #
@@ -93,8 +93,10 @@ module JsDuck
       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 substitute = @inline_img.replace(s)
+          out += substitute
+        elsif substitute = @inline_video.replace(s)
+          out += substitute
         elsif s.check(/[{]/)
           # There might still be "{" that doesn't begin {@link} or {@img} - ignore it
           out += s.scan(/[{]/)
@@ -185,10 +187,6 @@ module JsDuck
       end
     end
 
-    def replace_img_tag(input)
-      input.sub(@img_re) { img($1, $2) }
-    end
-
     # Looks input text for patterns like:
     #
     #  My.ClassName
@@ -258,21 +256,6 @@ module JsDuck
       Logger.instance.warn(:link_auto, msg, @doc_context[:filename], @doc_context[:linenr])
     end
 
-    # applies the image template
-    def img(url, alt_text)
-      @images << url
-      @img_tpl.gsub(/(%\w)/) do
-        case $1
-        when '%u'
-          @img_path ? (@img_path + "/" + url) : url
-        when '%a'
-          CGI.escapeHTML(alt_text||"")
-        else
-          $1
-        end
-      end
-    end
-
     # applies the link template
     def link(cls, member, anchor_text, type=nil, static=false)
       # Use the canonical class name for link (not some alternateClassName)
@@ -345,21 +328,25 @@ module JsDuck
     #
     def shorten(input)
       sent = first_sentence(strip_tags(input))
-      if sent.length > @max_length
-        sent[0..(@max_length-4)] + "..."
+      # Use u-modifier to correctly count multi-byte characters
+      chars = sent.scan(/./mu)
+      if chars.length > @max_length
+        chars[0..(@max_length-4)].join + "..."
       else
         sent + " ..."
       end
     end
 
     def first_sentence(str)
-      str.sub(/\A(.+?\.)\s.*\Z/m, "\\1")
+      str.sub(/\A(.+?(\.|。))\s.*\Z/mu, "\\1")
     end
 
     # Returns true when input should get shortened.
     def too_long?(input)
       stripped = strip_tags(input)
-      first_sentence(stripped).length < stripped.length || stripped.length > @max_length
+      # for sentence v/s full - compare byte length
+      # for full v/s max - compare char length
+      first_sentence(stripped).length < stripped.length || stripped.scan(/./mu).length > @max_length
     end
 
     def strip_tags(str)

data/lib/jsduck/doc_parser.rb

@@ -286,7 +286,9 @@ module JsDuck
       add_tag(:type)
       skip_horiz_white
       if look(/\{/)
-        @current_tag[:type] = typedef
+        tdf = typedef
+        @current_tag[:type] = tdf[:type]
+        @current_tag[:optional] = true if tdf[:optional]
       elsif look(/\S/)
         @current_tag[:type] = @input.scan(/\S+/)
       end
@@ -354,10 +356,13 @@ module JsDuck
     end
 
     # matches {type} if possible and sets it on @current_tag
+    # Also checks for {optionality=} in type definition.
     def maybe_type
       skip_horiz_white
       if look(/\{/)
-        @current_tag[:type] = typedef
+        tdf = typedef
+        @current_tag[:type] = tdf[:type]
+        @current_tag[:optional] = true if tdf[:optional]
       end
     end
 
@@ -431,12 +436,28 @@ module JsDuck
       end
     end
 
-    # matches {...} and returns text inside brackets
+    # matches {...=} and returns text inside brackets
     def typedef
       match(/\{/)
-      name = @input.scan(/[^}]+/)
+      name = @input.scan(/[^{}]*/)
+
+      # Type definition can contain nested braces: {{foo:Number}}
+      # In such case we parse the definition so that the braces are balanced.
+      while @input.check(/[{]/)
+        name += "{" + typedef[:type] +"}"
+        name += @input.scan(/[^{}]*/)
+      end
+
+      if name =~ /=$/
+        name = name.chop
+        optional = true
+      else
+        optional = nil
+      end
+
       match(/\}/)
-      return name
+
+      return {:type => name, :optional => optional}
     end
 
     # matches <ident_chain> <ident_chain> ... until line end

data/lib/jsduck/guides.rb

@@ -1,5 +1,6 @@
 require 'jsduck/logger'
 require 'jsduck/json_duck'
+require 'jsduck/io'
 require 'jsduck/null_object'
 require 'jsduck/logger'
 require 'jsduck/grouped_asset'
@@ -51,7 +52,7 @@ module JsDuck
       @formatter.doc_context = {:filename => guide_file, :linenr => 0}
       name = File.basename(in_dir)
       @formatter.img_path = "guides/#{name}"
-      html = add_toc(guide, @formatter.format(IO.read(guide_file)))
+      html = add_toc(guide, @formatter.format(JsDuck::IO.read(guide_file)))
 
       JsonDuck.write_jsonp(out_dir+"/README.js", name, {:guide => html, :title => guide["title"]})
     end

data/lib/jsduck/index_html.rb

@@ -1,4 +1,5 @@
 require 'jsduck/logger'
+require 'jsduck/io'
 require 'fileutils'
 
 module JsDuck
@@ -49,7 +50,7 @@ module JsDuck
     # Opens in_file, replaces {keys} inside it, writes to out_file
     def write_template(in_file, out_file, replacements)
       Logger.instance.log("Writing", out_file)
-      html = IO.read(in_file)
+      html = JsDuck::IO.read(in_file)
       html.gsub!(/\{\w+\}/) do |key|
         replacements[key] ? replacements[key] : key
       end

data/lib/jsduck/inline_img.rb

@@ -0,0 +1,53 @@
+require 'cgi'
+require 'jsduck/logger'
+
+module JsDuck
+
+  # Implementation of inline tag {@img}
+  class InlineImg
+    # Base path to prefix images from {@img} tags.
+    # Defaults to no prefix.
+    attr_accessor :base_path
+
+    # This will hold list of all image paths gathered from {@img} tags.
+    attr_accessor :images
+
+    def initialize(opts={})
+      @tpl = opts[:img_tpl] || '<img src="%u" alt="%a"/>'
+
+      @re = /\{@img\s+(\S*?)(?:\s+(.+?))?\}/m
+
+      @base_path = nil
+      @images = []
+    end
+
+    # Takes StringScanner instance.
+    #
+    # Looks for inline tag at the current scan pointer position, when
+    # found, moves scan pointer forward and performs the apporpriate
+    # replacement.
+    def replace(input)
+      if input.check(@re)
+        input.scan(@re).sub(@re) { apply_tpl($1, $2) }
+      else
+        false
+      end
+    end
+
+    # applies the image template
+    def apply_tpl(url, alt_text)
+      @images << url
+      @tpl.gsub(/(%\w)/) do
+        case $1
+        when '%u'
+          @base_path ? (@base_path + "/" + url) : url
+        when '%a'
+          CGI.escapeHTML(alt_text||"")
+        else
+          $1
+        end
+      end
+    end
+  end
+
+end

data/lib/jsduck/inline_video.rb

@@ -0,0 +1,58 @@
+require 'cgi'
+require 'jsduck/logger'
+
+module JsDuck
+
+  # Implementation of inline tag {@video}
+  class InlineVideo
+    def initialize(opts={})
+      @templates = {
+        "html5" => '<video src="%u">%a</video>',
+        "vimeo" => [
+          '<p><object width="640" height="360">',
+            '<param name="allowfullscreen" value="true" />',
+            '<param name="allowscriptaccess" value="always" />',
+            '<param name="flashvars" value="api=1" />',
+            '<param name="movie" value="http://vimeo.com/moogaloop.swf?clip_id=%u&amp;server=vimeo.com&amp;color=4CC208&amp;fullscreen=1" />',
+            '<embed src="http://vimeo.com/moogaloop.swf?clip_id=%u&amp;server=vimeo.com&amp;color=4CC208&amp;fullscreen=1" ',
+              'type="application/x-shockwave-flash" allowfullscreen="true" allowscriptaccess="always" width="640" height="360"></embed>',
+          '</object></p>',
+        ].join
+      }
+
+      @re = /\{@video\s+(\w+)\s+(\S*?)(?:\s+(.+?))?\}/m
+    end
+
+    # Takes StringScanner instance.
+    #
+    # Looks for inline tag at the current scan pointer position, when
+    # found, moves scan pointer forward and performs the apporpriate
+    # replacement.
+    def replace(input)
+      if input.check(@re)
+        input.scan(@re).sub(@re) { apply_tpl($1, $2, $3) }
+      else
+        false
+      end
+    end
+
+    # applies the video template of the specified type
+    def apply_tpl(type, url, alt_text)
+      unless @templates.has_key?(type)
+        Logger.instance.warn(nil, "Unknown video type #{type}")
+      end
+
+      @templates[type].gsub(/(%\w)/) do
+        case $1
+        when '%u'
+          url
+        when '%a'
+          CGI.escapeHTML(alt_text||"")
+        else
+          $1
+        end
+      end
+    end
+  end
+
+end

data/lib/jsduck/io.rb

@@ -0,0 +1,30 @@
+module JsDuck
+
+  # A helper to use instead the builtin IO class to read files in
+  # correct encoding.
+  #
+  # By default in Ruby 1.9 the encoding is auto-detected, which can
+  # have surprising results.  So in here we read in all files in UTF-8
+  # (the default) or in some other encoding specified through --encoding
+  # option and convert it to UTF-8 internally.
+  class IO
+    @@encoding = "UTF-8"
+
+    # Sets the external encoding to be used for reading files.
+    # When it's different from UTF-8, the input will be converted to UTF-8.
+    def self.encoding=(e)
+      if e =~ /^UTF-8$/i
+        @@encoding = e
+      else
+        @@encoding = e+":UTF-8"
+      end
+    end
+
+    # Reads given filename into string
+    def self.read(filename)
+      File.open(filename, "r:"+@@encoding) {|f| f.read }
+    end
+
+  end
+
+end