jsduck 4.6.1 → 4.6.2

data/.travis.yml

@@ -1,7 +1,7 @@
 language: ruby
 rvm:
   - "1.8.7"
-  - "1.9.2"
+  - "1.9.3"
 install:
   - gem install rdiscount
   - gem install json
@@ -9,3 +9,4 @@ install:
   - gem install therubyracer -v 0.10.1
   - gem install rspec
   - gem install rake
+  - gem install dimensions

data/README.md

@@ -11,8 +11,8 @@ the old [ext-doc][] was. It is used by Sencha to document [Ext JS
 products.
 
 The highlights of JSDuck are [Markdown][] support and keeping you DRY
-by inferring a lot of information from code.  Read the [Guide][] for
-full overview.
+by inferring a lot of information from code.  Read the
+[documentation][] for full overview.
 
 **New to JSDuck?** Watch [introductory talk by Nick Poulden][video]:
 
@@ -23,8 +23,8 @@ full overview.
 [Markdown]: http://daringfireball.net/projects/markdown/
 [ext4-docs]: http://docs.sencha.com/ext-js/4-0/
 [touch2-docs]: http://docs.sencha.com/touch/2-0/
-[other-docs]: http://docs.sencha.com/ext-js/4-0/
-[Guide]: https://github.com/senchalabs/jsduck/wiki/Guide
+[other-docs]: http://docs.sencha.com/
+[documentation]: https://github.com/senchalabs/jsduck/wiki
 [video]: http://vimeo.com/33465319
 
 Getting it
@@ -112,21 +112,15 @@ directories:
 Note that the resulting documentation will only contain the API
 documentation.  Guides, videos and examples will not be present.
 These can be added using more command line options as explained in the
-[Advanced Usage][adv] section of wiki.
-
-[adv]: https://github.com/senchalabs/jsduck/wiki/Advanced-Usage
+[documentation][].
 
 
 Documenting your code
 ---------------------
 
-For quick overview read the [Guide][] and take a look at [example.js][example].
-Follow links in the guide to digg into the details.
-
-Looking for specific @tag? Take a look at the [whole list of supported tags][tags].
+Read the [documentation][] and take a look at [example.js][example].
 
 [example]: https://github.com/senchalabs/jsduck/blob/master/opt/example.js
-[tags]: https://github.com/senchalabs/jsduck/wiki/Tags
 
 
 Hacking it

data/Rakefile

@@ -104,7 +104,7 @@ def compress
   dir = "template-min"
 
   # Create JSB3 file for Docs app
-  system("sencha", "create", "jsb", "-a", "http://localhost/docs/", "-p", "#{dir}/app.jsb3")
+  system("sencha", "create", "jsb", "-a", "http://localhost/~renesaarsoo/docs/", "-p", "#{dir}/app.jsb3")
   # Concatenate files listed in JSB3 file
   system("sencha", "build", "-p", "#{dir}/app.jsb3", "-d", dir)
 

data/js-classes/Date.js

@@ -234,7 +234,7 @@
 
 /**
  * @method getDate
- * Returns the numeric value corresponding to the current time.
+ * Returns the day of the month for the specified date according to local time.
  *
  * The second statement below assigns the value 25 to the variable `day`, based on the value of the
  * `Date` object `Xmas95`.
@@ -247,7 +247,7 @@
 
 /**
  * @method getDay
- * Returns the numeric value corresponding to the current time.
+ * Returns the day of the week for the specified date according to local time.
  *
  * The value returned by `getDay` is an integer corresponding to the day of the week: 0 for Sunday, 1
  * for Monday, 2 for Tuesday, and so on.
@@ -264,7 +264,7 @@
 
 /**
  * @method getFullYear
- * Returns the numeric value corresponding to the current time.
+ * Returns the year of the specified date according to local time.
  *
  * The value returned by `getFullYear` is an absolute number. For dates between the years 1000 and
  * 9999, `getFullYear` returns a four-digit number, for example, 1995. Use this function to make sure
@@ -282,7 +282,7 @@
 
 /**
  * @method getHours
- * Returns the numeric value corresponding to the current time.
+ * Returns the hour for the specified date according to local time.
  *
  * The second statement below assigns the value 23 to the variable `hours`, based on the value of the
  * `Date` object `Xmas95`.
@@ -295,7 +295,7 @@
 
 /**
  * @method getMilliseconds
- * Returns the numeric value corresponding to the current time.
+ * Returns the milliseconds in the specified date according to local time.
  *
  * The following example assigns the milliseconds portion of the current time to the variable ms.
  *
@@ -308,7 +308,7 @@
 
 /**
  * @method getMinutes
- * Returns the numeric value corresponding to the current time.
+ * Returns the minutes in the specified date according to local time.
  *
  * The second statement below assigns the value 15 to the variable `minutes`, based on the value of
  * the `Date` object `Xmas95`.
@@ -321,7 +321,7 @@
 
 /**
  * @method getMonth
- * Returns the numeric value corresponding to the current time.
+ * Returns the month in the specified date according to local time.
  *
  * The second statement below assigns the value 11 to the variable `month`, based on the value of the
  * `Date` object `Xmas95`.
@@ -334,7 +334,7 @@
 
 /**
  * @method getSeconds
- * Returns the numeric value corresponding to the current time.
+ * Returns the seconds in the specified date according to local time.
  *
  * The second statement below assigns the value 30 to the variable `secs`, based on the value of the
  * `Date` object `Xmas95`.
@@ -347,7 +347,8 @@
 
 /**
  * @method getTime
- * Returns the numeric value corresponding to the current time.
+ * Returns the numeric value corresponding to the time for the specified date according to
+ * universal time.
  *
  * The value returned by the `getTime` method is the number of milliseconds since 1 January 1970
  * 00:00:00 UTC. You can use this method to help assign a date and time to another `Date` object.
@@ -381,7 +382,7 @@
 
 /**
  * @method getTimezoneOffset
- * Returns the numeric value corresponding to the current time.
+ * Returns the time-zone offset from UTC, in minutes, for the current locale.
  *
  * The time-zone offset is the difference, in minutes, between UTC and local time. Note that this
  * means that the offset is positive if the local timezone is behind UTC and negative if it is ahead.
@@ -396,7 +397,7 @@
 
 /**
  * @method getUTCDate
- * Returns the numeric value corresponding to the current time.
+ * Returns the day (date) of the month in the specified date according to universal time.
  *
  * The following example assigns the day portion of the current date to the variable `d`.
  *
@@ -409,7 +410,7 @@
 
 /**
  * @method getUTCDay
- * Returns the numeric value corresponding to the current time.
+ * Returns the day of the week in the specified date according to universal time.
  *
  * The following example assigns the weekday portion of the current date to the variable `weekday`.
  *
@@ -423,7 +424,7 @@
 
 /**
  * @method getUTCFullYear
- * Returns the numeric value corresponding to the current time.
+ * Returns the year in the specified date according to universal time.
  *
  * The following example assigns the four-digit value of the current year to the variable `yr`.
  *
@@ -436,7 +437,7 @@
 
 /**
  * @method getUTCHours
- * Returns the numeric value corresponding to the current time.
+ * Returns the hours in the specified date according to universal time.
  *
  * The following example assigns the hours portion of the current time to the variable `hrs`.
  *
@@ -449,7 +450,7 @@
 
 /**
  * @method getUTCMilliseconds
- * Returns the numeric value corresponding to the current time.
+ * Returns the milliseconds in the specified date according to universal time.
  *
  * The following example assigns the milliseconds portion of the current time to the variable `ms`.
  *
@@ -462,7 +463,7 @@
 
 /**
  * @method getUTCMinutes
- * Returns the numeric value corresponding to the current time.
+ * Returns the minutes in the specified date according to universal time.
  *
  * The following example assigns the minutes portion of the current time to the variable `min`.
  *
@@ -475,7 +476,7 @@
 
 /**
  * @method getUTCMonth
- * Returns the numeric value corresponding to the current time.
+ * Returns the month of the specified date according to universal time.
  *
  * The following example assigns the month portion of the current date to the variable `mon`.
  *
@@ -488,7 +489,7 @@
 
 /**
  * @method getUTCSeconds
- * Returns the numeric value corresponding to the current time.
+ * Returns the seconds in the specified date according to universal time.
  *
  * The following example assigns the seconds portion of the current time to the variable `sec`.
  *

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.6.1'
-  s.date = '2013-01-17'
+  s.version = '4.6.2'
+  s.date = '2013-02-25'
   s.summary = "Simple JavaScript Duckumentation generator"
   s.description = "Documentation generator for Sencha JS frameworks"
   s.homepage = "https://github.com/senchalabs/jsduck"
@@ -23,6 +23,7 @@ Gem::Specification.new do |s|
   s.add_dependency 'json'
   s.add_dependency 'parallel'
   s.add_dependency 'therubyracer', '>= 0.10.0', '< 0.11.0'
+  s.add_dependency 'dimensions'
 
   s.add_development_dependency 'rspec'
   s.add_development_dependency 'rake'

data/lib/jsduck/assets.rb

@@ -1,4 +1,5 @@
-require 'jsduck/images'
+require 'jsduck/img/dir_set'
+require 'jsduck/img/writer'
 require 'jsduck/welcome'
 require 'jsduck/guides'
 require 'jsduck/videos'
@@ -26,10 +27,9 @@ module JsDuck
       @relations = relations
       @opts = opts
 
-      doc_formatter = DocFormatter.new(@opts)
-      doc_formatter.relations = @relations
+      doc_formatter = DocFormatter.new(@relations, @opts)
 
-      @images = Images.new(@opts.images)
+      @images = Img::DirSet.new(@opts.images, "images")
       @welcome = Welcome.create(@opts.welcome, doc_formatter)
       @guides = Guides.create(@opts.guides, doc_formatter, @opts)
       @videos = Videos.create(@opts.videos)
@@ -43,7 +43,7 @@ module JsDuck
     # Welcome page and categories are written in JsDuck::IndexHtml
     def write
       @guides.write(@opts.output_dir+"/guides")
-      @images.copy(@opts.output_dir+"/images")
+      Img::Writer.copy(@images.all_used, @opts.output_dir+"/images")
     end
 
   end

data/lib/jsduck/ast.rb

@@ -79,7 +79,7 @@ module JsDuck
         make_class(to_s(var["id"]), var["right"])
 
       # function Foo() {}
-      elsif function?(ast) && class_name?(to_s(ast["id"]))
+      elsif function?(ast) && ast["id"] && class_name?(to_s(ast["id"]))
         make_class(to_s(ast["id"]))
 
       # { ... }
@@ -88,7 +88,7 @@ module JsDuck
 
       # function foo() {}
       elsif function?(ast)
-        make_method(to_s(ast["id"]), ast)
+        make_method(ast["id"] ? to_s(ast["id"]) : "", ast)
 
       # foo = function() {}
       elsif exp && assignment?(exp) && function?(exp["right"])

data/lib/jsduck/batch_formatter.rb

@@ -1,6 +1,7 @@
 require 'jsduck/util/parallel'
 require 'jsduck/class_formatter'
 require 'jsduck/doc_formatter'
+require 'jsduck/img/dir_set'
 require 'jsduck/logger'
 
 module JsDuck
@@ -21,7 +22,7 @@ module JsDuck
         begin
           {
             :doc => formatter.format(cls.internal_doc),
-            :images => formatter.images
+            :images => formatter.images.all_used
           }
         rescue
           Logger.fatal_backtrace("Error while formatting #{cls[:name]} #{files}", $!)
@@ -32,15 +33,20 @@ module JsDuck
       # Then merge the data back to classes sequentially
       formatted_classes.each do |cls|
         relations[cls[:doc][:name]].internal_doc = cls[:doc]
-        cls[:images].each {|img| assets.images.add(img) }
+        # Perform lookup of all the images again.  We're really doing
+        # this work twice now, but as we usually don't have excessive
+        # amounts of images, the performance penalty should be minimal.
+        cls[:images].each {|img| assets.images.get(img[:filename]) }
       end
+
+      # Print warnings for unused images
+      assets.images.report_unused
     end
 
     # Factory method to create new ClassFormatter instances.
     def self.create_class_formatter(relations, opts)
-      doc_formatter = DocFormatter.new(opts)
-      doc_formatter.relations = relations
-      doc_formatter.img_path = "images"
+      doc_formatter = DocFormatter.new(relations, opts)
+      doc_formatter.images = Img::DirSet.new(opts.images, "images")
 
       class_formatter = ClassFormatter.new(relations, doc_formatter)
       # Don't format types when exporting

data/lib/jsduck/class_formatter.rb

@@ -33,7 +33,7 @@ module JsDuck
       cls
     end
 
-    # Returns the images detected by doc-formatter
+    # Access to the Img::DirSet object inside doc-formatter
     def images
       @formatter.images
     end

data/lib/jsduck/doc_formatter.rb

@@ -3,6 +3,8 @@ require 'strscan'
 require 'rdiscount'
 require 'jsduck/html_stack'
 require 'jsduck/inline/link'
+require 'jsduck/inline/auto_link'
+require 'jsduck/inline/link_renderer'
 require 'jsduck/inline/img'
 require 'jsduck/inline/video'
 require 'jsduck/inline/example'
@@ -15,21 +17,21 @@ module JsDuck
     # Creates a formatter configured with options originating from
     # command line.  For the actual effect of the options see
     # Inline::* classes.
-    def initialize(opts={})
+    def initialize(relations={}, opts={})
       @opts = opts
-      @inline_link = Inline::Link.new(opts)
+      @link_renderer = Inline::LinkRenderer.new(relations, opts)
+      @inline_link = Inline::Link.new(@link_renderer)
+      @auto_link = Inline::AutoLink.new(@link_renderer)
       @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.
-    def img_path=(path)
-      @inline_img.base_path = path
+    # Accessors to the images attribute of Inline::Img
+    def images=(images)
+      @inline_img.images = images
     end
-
-    # Returns list of all image paths gathered from {@img} tags.
     def images
       @inline_img.images
     end
@@ -39,6 +41,7 @@ module JsDuck
     # Context#blah is meant.
     def class_context=(cls)
       @inline_link.class_context = cls
+      @auto_link.class_context = cls
     end
 
     # Sets up instance to work in context of particular doc object.
@@ -47,6 +50,8 @@ module JsDuck
       @doc_context = doc
       @inline_video.doc_context = doc
       @inline_link.doc_context = doc
+      @auto_link.doc_context = doc
+      @inline_img.doc_context = doc
     end
 
     # Returns the current documentation context
@@ -54,15 +59,6 @@ module JsDuck
       @doc_context
     end
 
-    # 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.
-    def relations=(relations)
-      @inline_link.relations = relations
-    end
-
     # Formats doc-comment for placement into HTML.
     # Renders it with Markdown-formatter and replaces @link-s.
     def format(input)
@@ -114,13 +110,15 @@ module JsDuck
           # There might still be "{" that doesn't begin {@link} or {@img} - ignore it
           out += s.scan(/[{]/)
         elsif substitute = @inline_example.replace(s)
+          tags.push_tag("pre")
+          tags.push_tag("code")
           out += substitute
         elsif s.check(/<\w/)
           # Open HTML tag
-          out += s.scan(/</) + tags.open(s.scan(/\w+/)) + s.scan_until(/>|\Z/)
+          out += tags.open(s)
         elsif s.check(/<\/\w+>/)
           # Close HTML tag
-          out += s.scan(/<\//) + tags.close(s.scan(/\w+/)) + s.scan(/>/)
+          out += tags.close(s)
         elsif s.check(/</)
           # Ignore plain '<' char.
           out += s.scan(/</)
@@ -128,16 +126,16 @@ module JsDuck
           # Replace class names in the following text up to next "<" or "{"
           # but only when we're not inside <a>...</a>
           text = s.scan(/[^{<]+/)
-          out += tags.open?("a") ? text : @inline_link.create_magic_links(text)
+          out += tags.open?("a") ? text : @auto_link.replace(text)
         end
       end
 
-      out + tags.close_unfinished
+      out
     end
 
     # Creates a link based on the link template.
     def link(cls, member, anchor_text, type=nil, static=nil)
-      @inline_link.link(cls, member, anchor_text, type, static)
+      @link_renderer.link(cls, member, anchor_text, type, static)
     end
 
   end

data/lib/jsduck/doc_parser.rb

@@ -176,7 +176,7 @@ module JsDuck
     end
 
     def indented_as_code?
-      @current_tag[:doc] =~ /^ {4,}[^\n]*\Z/
+      @current_tag[:doc] =~ /^ {4,}[^\n]*\z/
     end
 
     # Processes anything else beginning with @-sign.