jsduck 4.10.4 → 5.0.0.beta01

data/lib/jsduck/format/shortener.rb

@@ -0,0 +1,55 @@
+# -*- coding: utf-8 -*-
+require 'jsduck/util/html'
+
+module JsDuck
+  module Format
+
+    # Little helper for shortening text
+    class Shortener
+      # Takes as parameter the maximum length for text that doesn't
+      # get shortened.  Used for testing purposes.
+      def initialize(max_length = 120)
+        @max_length = max_length
+      end
+
+      # Shortens text
+      #
+      # 116 chars is also where ext-doc makes its cut, but unlike
+      # ext-doc we only make the cut when there's more than 120 chars.
+      #
+      # This way we don't get stupid expansions like:
+      #
+      #   Blah blah blah some text...
+      #
+      # expanding to:
+      #
+      #   Blah blah blah some text.
+      #
+      def shorten(input)
+        sent = first_sentence(Util::HTML.strip_tags(input).strip)
+        # 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
+
+      # Returns the first sentence inside a string.
+      def first_sentence(str)
+        str.sub(/\A(.+?(\.|。))\s.*\z/mu, "\\1")
+      end
+
+      # Returns true when input should get shortened.
+      def too_long?(input)
+        stripped = Util::HTML.strip_tags(input).strip
+        # 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
+
+    end
+
+  end
+end

data/lib/jsduck/format/subproperties.rb

@@ -0,0 +1,64 @@
+require 'jsduck/util/html'
+require 'jsduck/logger'
+require 'jsduck/type_parser'
+
+module JsDuck
+  module Format
+
+    # Helper for recursively formatting subproperties.
+    class Subproperties
+
+      def initialize(formatter)
+        @formatter = formatter
+        @skip_type_parsing = false
+      end
+
+      # Set to true to skip parsing and formatting of types.
+      # Used to skip parsing of CSS typesdefs.
+      attr_accessor :skip_type_parsing
+
+      # Takes a hash of param, return value, throws value or subproperty.
+      #
+      # - Markdown-formats the :doc field in it.
+      # - Parses the :type field and saves HTML to :html_type.
+      # - Recursively does the same with all items in :properties field.
+      #
+      def format(item)
+        item[:doc] = @formatter.format(item[:doc]) if item[:doc]
+
+        if item[:type]
+          item[:html_type] = format_type(item[:type])
+        end
+
+        if item[:properties]
+          item[:properties].each {|p| format(p) }
+        end
+      end
+
+      # Formats the given type definition string using TypeParser.
+      #
+      # - On success returns HTML-version of the type definition.
+      # - On failure logs error and returns the type string with only HTML escaped.
+      #
+      def format_type(type)
+        # Skip the formatting entirely when type-parsing is turned off.
+        return Util::HTML.escape(type) if @skip_type_parsing
+
+        tp = TypeParser.new(@formatter)
+        if tp.parse(type)
+          tp.out
+        else
+          context = @formatter.doc_context
+          if tp.error == :syntax
+            Logger.warn(:type_syntax, "Incorrect type syntax #{type}", context[:filename], context[:linenr])
+          else
+            Logger.warn(:type_name, "Unknown type #{type}", context[:filename], context[:linenr])
+          end
+          Util::HTML.escape(type)
+        end
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/guides.rb

@@ -4,8 +4,7 @@ require 'jsduck/util/io'
 require 'jsduck/util/null_object'
 require 'jsduck/logger'
 require 'jsduck/grouped_asset'
-require 'jsduck/guide_toc'
-require 'jsduck/guide_anchors'
+require 'jsduck/util/html'
 require 'jsduck/img/dir'
 require 'fileutils'
 
@@ -56,10 +55,6 @@ 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)
@@ -72,9 +67,7 @@ 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 = @formatter.format(Util::IO.read(guide[:filename]))
-      html = GuideToc.inject(html, guide['name'])
-      html = GuideAnchors.transform(html, guide['name'])
+      html = add_toc(guide, @formatter.format(Util::IO.read(guide[:filename])))
 
       # Report unused images (but ignore the icon files)
       @formatter.images.get("icon.png")
@@ -109,11 +102,6 @@ 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.
@@ -127,6 +115,36 @@ 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/index_html.rb

@@ -37,10 +37,10 @@ module JsDuck
         "{data_path}" => File.basename(@opts.data_path),
         "{welcome}" => @assets.welcome.to_html("display:none"),
         "{categories}" => @assets.categories.to_html("display:none"),
-        "{news}" => @assets.news.to_html("display:none"),
         "{guides}" => @assets.guides.to_html("display:none"),
         "{head_html}" => @opts.head_html,
         "{body_html}" => @opts.body_html,
+        "{head_css}" => TagRegistry.css,
       })
     end
 
@@ -48,6 +48,7 @@ module JsDuck
       write_template(in_file, out_file, {
         "{title}" => @opts.title,
         "{header}" => @opts.header,
+        "{head_css}" => TagRegistry.css,
       })
     end
 
@@ -60,6 +61,7 @@ module JsDuck
         "{header}" => @opts.header,
         "{categories}" => categories ? "<h1>API Documentation</h1> #{categories}" : "",
         "{guides}" => guides ? "<h1>Guides</h1> #{guides}" : "",
+        "{head_css}" => TagRegistry.css,
       })
     end
 

data/lib/jsduck/inline/auto_link.rb

@@ -71,7 +71,7 @@ module JsDuck
             cls2, member2 = split_to_cls_and_member(cls)
             if @relations[cls2] && @renderer.get_matching_member(cls2, {:name => member2})
               return @renderer.link(cls2, member2, cls2+"."+member2)
-            elsif cls =~ /\.(js|css|html|php)\Z/
+            elsif cls =~ /\.(js|css|html|php)\z/
               # Ignore common filenames
             else
               warn_magic_link("#{cls} links to non-existing class")
@@ -80,7 +80,7 @@ module JsDuck
         else
           if @renderer.get_matching_member(@class_context, {:name => member})
             return @renderer.link(@class_context, member, member)
-          elsif member =~ /\A([A-F0-9]{3}|[A-F0-9]{6})\Z/i || member =~ /\A[0-9]/
+          elsif member =~ /\A([A-F0-9]{3}|[A-F0-9]{6})\z/i || member =~ /\A[0-9]/
             # Ignore HEX color codes and
             # member names beginning with number
           else

data/lib/jsduck/inline/link.rb

@@ -1,4 +1,5 @@
 require 'jsduck/logger'
+require 'jsduck/tag_registry'
 
 module JsDuck
   module Inline
@@ -40,7 +41,7 @@ module JsDuck
 
       # applies the link template
       def apply_tpl(target, text, full_link)
-        if target =~ /^(.*)#(static-)?(?:(cfg|property|method|event|css_var|css_mixin)-)?(.*)$/
+        if target =~ /^(.*)#(static-)?#{TagRegistry.member_type_regex}?(.*)$/
           cls = $1.empty? ? @class_context : $1
           static = $2 ? true : nil
           type = $3 ? $3.intern : nil
@@ -78,12 +79,12 @@ module JsDuck
             # one when we ignore the static members. If there's more,
             # report ambiguity. If there's only static members, also
             # report ambiguity.
-            instance_ms = ms.find_all {|m| !m[:meta][:static] }
+            instance_ms = ms.find_all {|m| !m[:static] }
             if instance_ms.length > 1
               alternatives = instance_ms.map {|m| "#{m[:tagname]} in #{m[:owner]}" }.join(", ")
               Logger.warn(:link_ambiguous, "#{full_link} is ambiguous: "+alternatives, file, line)
             elsif instance_ms.length == 0
-              static_ms = ms.find_all {|m| m[:meta][:static] }
+              static_ms = ms.find_all {|m| m[:static] }
               alternatives = static_ms.map {|m| "static " + m[:tagname].to_s }.join(", ")
               Logger.warn(:link_ambiguous, "#{full_link} is ambiguous: "+alternatives, file, line)
             end

data/lib/jsduck/inline/link_renderer.rb

@@ -52,8 +52,8 @@ module JsDuck
       def get_matching_member(cls, query)
         ms = find_members(cls, query)
         if ms.length > 1
-          instance_ms = ms.find_all {|m| !m[:meta][:static] }
-          instance_ms.length > 0 ? instance_ms[0] : ms.find_all {|m| m[:meta][:static] }[0]
+          instance_ms = ms.find_all {|m| !m[:static] }
+          instance_ms.length > 0 ? instance_ms[0] : ms.find_all {|m| m[:static] }[0]
         else
           ms[0]
         end

data/lib/jsduck/inline/video.rb

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

data/lib/jsduck/js/ast.rb

@@ -0,0 +1,361 @@
+require "jsduck/js/function"
+require "jsduck/js/node"
+require "jsduck/tag_registry"
+
+module JsDuck
+  module Js
+
+    # Analyzes the AST produced by EsprimaParser.
+    class Ast
+      # Should be initialized with EsprimaParser#parse result.
+      def initialize(docs = [])
+        @docs = docs
+      end
+
+      # Performs the detection of code in all docsets.
+      #
+      # @returns the processed array of docsets. (But it does it
+      # destructively by modifying the passed-in docsets.)
+      #
+      def detect_all!
+        # First deal only with doc-comments
+        doc_comments = @docs.find_all {|d| d[:type] == :doc_comment }
+
+        # Detect code in each docset.  Sometimes a docset has already
+        # been detected as part of detecting some previous docset (like
+        # Class detecting all of its configs) - in such case, skip.
+        doc_comments.each do |docset|
+          code = docset[:code]
+          docset[:code] = detect(code) unless code && code[:tagname]
+        end
+
+        # Return all doc-comments + other comments for which related
+        # code was detected.
+        @docs.find_all {|d| d[:type] == :doc_comment || d[:code] && d[:code][:tagname] }
+      end
+
+      # Given Esprima-produced syntax tree, detects documentation data.
+      #
+      # This method is exposed for testing purposes only, JSDuck itself
+      # only calls the above #detect_all method.
+      #
+      # @param ast :code from Result of EsprimaParser
+      # @returns Hash consisting of the detected :tagname, :name, and
+      # other properties relative to the tag.  Like so:
+      #
+      #     { :tagname => :method, :name => "foo", ... }
+      #
+      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)
+
+        else
+          make_property()
+        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] = true
+        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
+end