jsduck 5.0.0.beta2 → 5.0.0.beta3

data/lib/jsduck/guide_anchors.rb

@@ -0,0 +1,32 @@
+module JsDuck
+
+  # Transforms in-page links so they won't break docs app #!-navigation.
+  #
+  # For example a link to "#automation" in testing guide will be
+  # replaced with "#!/guide/testing-section-automation" and the link
+  # target ID will be transformed into "testing-section-automation".
+  class GuideAnchors
+
+    def self.transform(html, guide_name)
+      html.gsub(/(<a\s+(?:[^<>]*\s+)?href=['"]#)([^!\/].*?)(['"])/i) do |m|
+        "#{$1}!/guide/#{guide_name}-section-#{$2}#{$3}"
+
+      end.gsub(/(<a\s+(?:[^<>]*\s+)?name=['"])(.*?)(['"])/i) do |m|
+        $1 + transform_id($2, guide_name) + $3
+
+      end.gsub(/(<\w+\s+(?:[^<>]*\s+)?id=['"])(.*?)(['"])/i) do |m|
+        $1 + transform_id($2, guide_name) + $3
+      end
+    end
+
+    def self.transform_id(id, guide_name)
+      if id =~ /^#{guide_name}-section-/
+        id
+      else
+        "#{guide_name}-section-#{id}"
+      end
+    end
+
+  end
+
+end

data/lib/jsduck/guide_toc.rb

@@ -0,0 +1,49 @@
+require 'jsduck/util/html'
+
+module JsDuck
+
+  # Adds Table of Contents section to guide HTML.
+  class GuideToc
+
+    # Inserts table of contents at the top of guide HTML by looking
+    # for <h2> elements.
+    def self.inject(html, guide_name)
+      toc = []
+      new_html = []
+
+      html.each_line do |line|
+        if line =~ /^\s*<(h[1-6])>(.*?)<\/h[1-6]>$/
+          tag = $1
+          text = Util::HTML.strip_tags($2)
+          id = guide_name + "-section-" + title_to_id(text)
+          if tag == "h2"
+            toc << "<li><a href='#!/guide/#{id}'>#{text}</a></li>\n"
+          end
+          new_html << "<#{tag} id='#{id}'>#{text}</#{tag}>\n"
+        else
+          new_html << line
+        end
+      end
+
+      # Inject TOC below first heading if at least 2 items in TOC
+      if toc.length >= 2
+        new_html.insert(1, [
+            "<div class='toc'>\n",
+            "<p><strong>Contents</strong></p>\n",
+            "<ol>\n",
+            toc,
+            "</ol>\n",
+            "</div>\n",
+        ])
+      end
+
+      new_html.flatten.join
+    end
+
+    def self.title_to_id(title)
+      title.downcase.gsub(/[^\w]+/, "-")
+    end
+
+  end
+
+end

data/lib/jsduck/guides.rb

@@ -4,7 +4,8 @@ require 'jsduck/util/io'
 require 'jsduck/util/null_object'
 require 'jsduck/logger'
 require 'jsduck/grouped_asset'
-require 'jsduck/util/html'
+require 'jsduck/guide_toc'
+require 'jsduck/guide_anchors'
 require 'jsduck/img/dir'
 require 'fileutils'
 
@@ -55,6 +56,10 @@ module JsDuck
     def load_guide(guide)
       return Logger.warn(:guide, "Guide not found", guide["url"]) unless File.exists?(guide["url"])
       return Logger.warn(:guide, "Guide not found", guide[:filename]) unless File.exists?(guide[:filename])
+      unless js_ident?(guide["name"])
+        # Guide name is also used as JSONP callback method name.
+        return Logger.warn(:guide, "Guide name is not valid JS identifier: #{guide["name"]}", guide[:filename])
+      end
 
       begin
         return format_guide(guide)
@@ -67,7 +72,9 @@ module JsDuck
     def format_guide(guide)
       @formatter.doc_context = {:filename => guide[:filename], :linenr => 0}
       @formatter.images = Img::Dir.new(guide["url"], "guides/#{guide["name"]}")
-      html = add_toc(guide, @formatter.format(Util::IO.read(guide[:filename])))
+      html = @formatter.format(Util::IO.read(guide[:filename]))
+      html = GuideToc.inject(html, guide['name'])
+      html = GuideAnchors.transform(html, guide['name'])
 
       # Report unused images (but ignore the icon files)
       @formatter.images.get("icon.png")
@@ -102,6 +109,11 @@ module JsDuck
       end
     end
 
+    # True when string is valid JavaScript identifier
+    def js_ident?(str)
+      /\A[$\w]+\z/ =~ str
+    end
+
     # Ensures the guide dir contains icon.png.
     # When there isn't looks for icon-lg.png and renames it to icon.png.
     # When neither exists, copies over default icon.
@@ -115,36 +127,6 @@ module JsDuck
       end
     end
 
-    # Creates table of contents at the top of guide by looking for <h2> elements in HTML.
-    def add_toc(guide, html)
-      toc = [
-        "<div class='toc'>\n",
-        "<p><strong>Contents</strong></p>\n",
-        "<ol>\n",
-      ]
-      new_html = []
-      i = 0
-      html.each_line do |line|
-        if line =~ /^<h2>(.*)<\/h2>$/
-          i += 1
-          text = Util::HTML.strip_tags($1)
-          toc << "<li><a href='#!/guide/#{guide['name']}-section-#{i}'>#{text}</a></li>\n"
-          new_html << "<h2 id='#{guide['name']}-section-#{i}'>#{text}</h2>\n"
-        else
-          new_html << line
-        end
-      end
-      toc << "</ol>\n"
-      toc << "</div>\n"
-      # Inject TOC at below first heading if at least 2 items in TOC
-      if i >= 2
-        new_html.insert(1, toc)
-        new_html.flatten.join
-      else
-        html
-      end
-    end
-
     # Returns HTML listing of guides
     def to_html(style="")
       html = @groups.map do |group|

data/lib/jsduck/inline/video.rb

@@ -16,14 +16,8 @@ module JsDuck
         @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>',
+            '<p><iframe src="http://player.vimeo.com/video/%u" width="640" height="360" frameborder="0" ',
+                'webkitAllowFullScreen mozallowfullscreen allowFullScreen></iframe></p>'
           ].join
         }
 

data/lib/jsduck/js/ast.rb

@@ -1,6 +1,8 @@
-require "jsduck/js/function"
+require "jsduck/js/class"
+require "jsduck/js/method"
+require "jsduck/js/event"
+require "jsduck/js/property"
 require "jsduck/js/node"
-require "jsduck/tag_registry"
 
 module JsDuck
   module Js
@@ -48,313 +50,19 @@ module JsDuck
       def detect(node)
         ast = Js::Node.create(node)
 
-        exp = ast.expression_statement? ? ast["expression"] : nil
-        var = ast.variable_declaration? ? ast["declarations"][0] : nil
-
-        # Ext.define("Class", {})
-        if exp && exp.ext_define?
-          make_class(exp["arguments"][0].to_value, exp)
-
-          # Ext.override(Class, {})
-        elsif exp && exp.ext_override?
-          make_class("", exp)
-
-          # foo = Ext.extend(Parent, {})
-        elsif exp && exp.assignment_expression? && exp["right"].ext_extend?
-          make_class(exp["left"].to_s, exp["right"])
-
-          # Foo = ...
-        elsif exp && exp.assignment_expression? && class_name?(exp["left"].to_s)
-          make_class(exp["left"].to_s, exp["right"])
-
-          # var foo = Ext.extend(Parent, {})
-        elsif var && var["init"].ext_extend?
-          make_class(var["id"].to_s, var["init"])
-
-          # var Foo = ...
-        elsif var && class_name?(var["id"].to_s)
-          make_class(var["id"].to_s, var["right"])
-
-          # function Foo() {}
-        elsif ast.function? && class_name?(ast["id"].to_s || "")
-          make_class(ast["id"].to_s)
-
-          # { ... }
-        elsif ast.object_expression?
-          make_class("", ast)
-
-          # function foo() {}
-        elsif ast.function?
-          make_method(ast["id"].to_s || "", ast)
-
-          # foo = function() {}
-        elsif exp && exp.assignment_expression? && exp["right"].function?
-          make_method(exp["left"].to_s, exp["right"])
-
-          # var foo = function() {}
-        elsif var && var["init"] && var["init"].function?
-          make_method(var["id"].to_s, var["init"])
-
-          # (function() {})
-        elsif exp && exp.function?
-          make_method(exp["id"].to_s || "", exp)
-
-          # foo: function() {}
-        elsif ast.property? && ast["value"].function?
-          make_method(ast["key"].key_value, ast["value"])
-
-          # this.fireEvent("foo", ...)
-        elsif exp && exp.fire_event?
-          make_event(exp["arguments"][0].to_value)
-
-          # foo = ...
-        elsif exp && exp.assignment_expression?
-          make_property(exp["left"].to_s, exp["right"])
-
-          # var foo = ...
-        elsif var
-          make_property(var["id"].to_s, var["init"])
-
-          # foo: ...
-        elsif ast.property?
-          make_property(ast["key"].key_value, ast["value"])
-
-          # foo;
-        elsif exp && exp.identifier?
-          make_property(exp.to_s)
-
-          # "foo"  (inside some expression)
-        elsif ast.string?
-          make_property(ast.to_value)
-
-          # "foo";  (as a statement of it's own)
-        elsif exp && exp.string?
-          make_property(exp.to_value)
-
+        if doc = Js::Class.detect(ast, @docs)
+          doc
+        elsif doc = Js::Method.detect(ast)
+          doc
+        elsif doc = Js::Event.detect(ast)
+          doc
+        elsif doc = Js::Property.detect(ast)
+          doc
         else
-          make_property()
+          Js::Property.make()
         end
       end
 
-      private
-
-      # Class name begins with upcase char
-      def class_name?(name)
-        return name.split(/\./).last =~ /\A[A-Z]/
-      end
-
-      def make_class(name, ast=nil)
-        cls = {
-          :tagname => :class,
-          :name => name,
-        }
-
-        # apply information from Ext.extend, Ext.define, or {}
-        if ast
-          if ast.ext_define?
-            detect_ext_define(cls, ast)
-          elsif ast.ext_extend?
-            detect_ext_something(:extends, cls, ast)
-          elsif ast.ext_override?
-            detect_ext_something(:override, cls, ast)
-          elsif ast.object_expression?
-            detect_class_members_from_object(cls, ast)
-          elsif ast.array_expression?
-            detect_class_members_from_array(cls, ast)
-          end
-        end
-
-        return cls
-      end
-
-      # Detection of Ext.extend() or Ext.override().
-      # The type parameter must be correspondingly either :extend or :override.
-      def detect_ext_something(type, cls, ast)
-        args = ast["arguments"]
-        cls[type] = args[0].to_s
-        if args.length == 2 && args[1].object_expression?
-          detect_class_members_from_object(cls, args[1])
-        end
-      end
-
-      # Inspects Ext.define() and copies detected properties over to the
-      # given cls Hash
-      def detect_ext_define(cls, ast)
-        # defaults
-        cls.merge!(TagRegistry.ext_define_defaults)
-        cls[:members] = []
-        cls[:code_type] = :ext_define
-
-        ast["arguments"][1].each_property do |key, value, pair|
-          if tag = TagRegistry.get_by_ext_define_pattern(key)
-            tag.parse_ext_define(cls, value)
-          else
-            case key
-            when "config"
-              cls[:members] += make_configs(value, {:accessor => true})
-            when "cachedConfig"
-              cls[:members] += make_configs(value, {:accessor => true})
-            when "eventedConfig"
-              cls[:members] += make_configs(value, {:accessor => true, :evented => true})
-            when "statics"
-              cls[:members] += make_statics(value)
-            when "inheritableStatics"
-              cls[:members] += make_statics(value, {:inheritable => true})
-            else
-              detect_method_or_property(cls, key, value, pair)
-            end
-          end
-        end
-      end
-
-      # Detects class members from object literal
-      def detect_class_members_from_object(cls, ast)
-        cls[:members] = []
-        ast.each_property do |key, value, pair|
-          detect_method_or_property(cls, key, value, pair)
-        end
-      end
-
-      # Detects class members from array literal
-      def detect_class_members_from_array(cls, ast)
-        cls[:members] = []
-
-        # This will most likely be an @enum class, in which case the
-        # enum will be for documentation purposes only.
-        cls[:enum] = {:doc_only => true}
-
-        ast["elements"].each do |el|
-          detect_method_or_property(cls, el.key_value, el, el)
-        end
-      end
-
-      # Detects item in object literal either as method or property
-      def detect_method_or_property(cls, key, value, pair)
-        if value.function?
-          m = make_method(key, value)
-          cls[:members] << m if apply_autodetected(m, pair)
-        else
-          p = make_property(key, value)
-          cls[:members] << p if apply_autodetected(p, pair)
-        end
-      end
-
-      def make_configs(ast, defaults={})
-        configs = []
-
-        ast.each_property do |name, value, pair|
-          cfg = make_property(name, value, :cfg)
-          cfg.merge!(defaults)
-          configs << cfg if apply_autodetected(cfg, pair)
-        end
-
-        configs
-      end
-
-      def make_statics(ast, defaults={})
-        statics = []
-
-        ast.each_property do |name, value, pair|
-          if value.function?
-            s = make_method(name, value)
-          else
-            s = make_property(name, value)
-          end
-
-          s[:static] = true
-          s.merge!(defaults)
-
-          statics << s if apply_autodetected(s, pair, defaults[:inheritable])
-        end
-
-        statics
-      end
-
-      # Sets auto-detection related properties :autodetected and
-      # :inheritdoc on the given member Hash.
-      #
-      # When member has a comment, adds code to the related docset and
-      # returns false.
-      #
-      # Otherwise detects the line number of member and returns true.
-      def apply_autodetected(m, ast, inheritable=true)
-        docset = find_docset(ast.raw)
-
-        if !docset || docset[:type] != :doc_comment
-          if inheritable
-            m[:inheritdoc] = {}
-          else
-            m[:private] = true
-          end
-          m[:autodetected] = {:tagname => m[:tagname]}
-        end
-
-        if docset
-          docset[:code] = m
-          return false
-        else
-          m[:linenr] = ast.linenr
-          return true
-        end
-      end
-
-      # Looks up docset associated with given AST node.
-      # A dead-stupid and -slow implementation, but works.
-      #
-      # The comparison needs to be done between raw AST nodes - multiple
-      # Node instances can be created to wrap a single raw AST node,
-      # and they will then not be equal.
-      def find_docset(raw_ast)
-        @docs.find do |docset|
-          docset[:code] == raw_ast
-        end
-      end
-
-      def make_method(name, ast)
-        return {
-          :tagname => :method,
-          :name => name,
-          :params => make_params(ast),
-          :chainable => chainable?(ast) && name != "constructor",
-        }
-      end
-
-      def make_params(ast)
-        if ast.function? && !ast.ext_empty_fn?
-          ast["params"].map {|p| {:name => p.to_s} }
-        else
-          []
-        end
-      end
-
-      def chainable?(ast)
-        if ast.function? && !ast.ext_empty_fn?
-          Js::Function.return_types(ast.raw) == [:this]
-        else
-          false
-        end
-      end
-
-      def make_event(name)
-        return {
-          :tagname => :event,
-          :name => name,
-        }
-      end
-
-      def make_property(name=nil, ast=nil, tagname=:property)
-        return {
-          :tagname => tagname,
-          :name => name,
-          :type => ast && ast.value_type,
-          :default => ast && make_default(ast),
-        }
-      end
-
-      def make_default(ast)
-        ast.to_value != nil ? ast.to_s : nil
-      end
-
     end
 
   end