jsduck 0.6.1 → 2.0.pre

data/lib/jsduck/guides.rb

@@ -0,0 +1,110 @@
+require 'jsduck/jsonp'
+require 'jsduck/logger'
+require 'fileutils'
+
+module JsDuck
+
+  # Reads in guides and converts them to JsonP files
+  class Guides
+    def initialize(formatter, order=nil)
+      @guides = []
+      @formatter = formatter
+      @order = order
+    end
+
+    # Looks for guide in each subdir of given directory.
+    def parse_dir(guides_dir)
+      Dir.glob(guides_dir + "/*").each do |dir|
+        if File.directory?(dir)
+          parse_guide(dir)
+        end
+      end
+
+      if @order
+        # When order specified, place guides into that order and
+        # exclude those guides that aren't listed in @order
+        @guides = @order.map {|name| @guides.find {|g| g[:name] =~ Regexp.new("^"+Regexp.escape(name)) } }
+      else
+        # Otherwise sort guides alphabetically
+        @guides.sort! {|a, b| a[:title] <=> b[:title] }
+      end
+    end
+
+    def parse_guide(dir)
+      guide_file = dir + "/README.md"
+      unless File.exists?(guide_file)
+        return Logger.instance.warn("README.md not found in #{dir}")
+      end
+
+      Logger.instance.log("Parsing guide #{guide_file} ...")
+      markdown = IO.read(guide_file)
+      name = File.basename(dir)
+      # Treat the first line of file as title
+      title = markdown.match(/^#\s*([^\n]*?)(\r?\n|$)/)[1]
+
+      @formatter.doc_context = {:filename => guide_file, :linenr => 0}
+      html = @formatter.format(markdown)
+      html.gsub!(/<img src="/, "<img src=\"guides/#{name}/")
+
+      @guides << {
+        :dir => dir,
+        :name => name,
+        :title => title,
+        :icon => File.exists?(dir+"/icon.png"),
+        :html => html,
+      }
+    end
+
+    # Writes all guides to given dir in JsonP format
+    def write(dir)
+      # Skip it all when we have no guides
+      FileUtils.mkdir(dir) if @guides.length > 0
+
+      @guides.each do |guide|
+        out_dir = dir+"/"+guide[:name]
+        FileUtils.cp_r(guide[:dir], out_dir)
+        # Write the JsonP file and remove the original Markdown file
+        JsonP.write(out_dir+"/README.js", guide[:name], {:guide => guide[:html]})
+        FileUtils.rm(out_dir + "/README.md")
+      end
+    end
+
+    # Returns HTML listing of guides
+    def to_html
+      return "" if @guides.length == 0
+
+      links = @guides.map do |g|
+        style = g[:icon] ? "style='background: url(guides/#{g[:name]}/icon.png) no-repeat'" : ""
+        "<a class='guide' rel='#{g[:name]}' #{style} href='#/guide/#{g[:name]}'>#{g[:title]}</a>"
+      end
+
+      # Divide to three columns: lft, mid, rgt
+      col_height = (links.length / 3).ceil
+      return <<-EOHTML
+        <div id='guides-content' style='display:none'>
+            <div class="lft">
+                #{links.slice(0, col_height).join("\n")}
+            </div>
+            <div class="mid">
+                #{links.slice(col_height, col_height).join("\n")}
+            </div>
+            <div class="rgt">
+                #{links.slice(col_height*2, col_height).join("\n")}
+            </div>
+        </div>
+      EOHTML
+    end
+
+    # Iterates over each guide
+    def each(&block)
+      @guides.each &block
+    end
+
+    # Returns number of guides
+    def length
+      @guides.length
+    end
+
+  end
+
+end

data/lib/jsduck/js_parser.rb

@@ -195,7 +195,7 @@ module JsDuck
       cfg
     end
 
-    # <ext-define-cfg> := "{" ( <extend> | <mixins> | <alternate-class-name> | <?> )*
+    # <ext-define-cfg> := "{" ( <extend> | <mixins> | <alternate-class-name> | <alias> | <?> )*
     def ext_define_cfg
       match("{")
       cfg = {}
@@ -209,7 +209,10 @@ module JsDuck
           cfg[:mixins] = ext_define_mixins
           found = true
         elsif look("alternateClassName", ":")
-          cfg[:alternateClassNames] = ext_define_alternate_class_name
+          cfg[:alternateClassNames] = ext_define_alternate_class_names
+          found = true
+        elsif look("alias", ":")
+          cfg[:alias] = ext_define_alias
           found = true
         elsif look(:ident, ":")
           match(:ident, ":")
@@ -234,9 +237,20 @@ module JsDuck
       match("extend", ":", :string)
     end
 
-    # <ext-define-alternate-class-name> := "alternateClassName" ":" ( <string> | <array-of-strings> )
-    def ext_define_alternate_class_name
+    # <ext-define-alternate-class-names> := "alternateClassName" ":" <string-or-list>
+    def ext_define_alternate_class_names
       match("alternateClassName", ":")
+      string_or_list
+    end
+
+    # <ext-define-alias> := "alias" ":" <string-or-list>
+    def ext_define_alias
+      match("alias", ":")
+      string_or_list
+    end
+
+    # <string-or-list> := ( <string> | <array-of-strings> )
+    def string_or_list
       if look(:string)
         [ match(:string) ]
       elsif look("[")

data/lib/jsduck/jsonp.rb

@@ -0,0 +1,17 @@
+require 'json'
+
+module JsDuck
+
+  # Utility class for writing JsonP files
+  class JsonP
+
+    # Turns hash into JSON and writes inside JavaScript that calls the
+    # given callback name
+    def self.write(filename, callback_name, data)
+      jsonp = "Ext.data.JsonP." + callback_name + "(" + JSON.pretty_generate(data) + ");"
+      File.open(filename, 'w') {|f| f.write(jsonp) }
+    end
+
+  end
+
+end

data/lib/jsduck/logger.rb

@@ -0,0 +1,36 @@
+require 'singleton'
+
+module JsDuck
+
+  # Central logging of JsDuck
+  class Logger
+    include Singleton
+
+    attr_accessor :verbose
+    attr_accessor :warnings
+
+    def initialize
+      @verbose = false
+      @warnings = true
+      @shown_warnings = {}
+    end
+
+    # Prints log message
+    def log(msg)
+      puts msg if @verbose
+    end
+
+    # Prints warning message.
+    #
+    # Ignores duplicate warnings - only prints the first one.
+    # Works best when --processes=0, but it reduces the amount of
+    # warnings greatly also when run multiple processes.
+    def warn(msg)
+      if @warnings && !@shown_warnings[msg]
+        puts "Warning: " + msg
+        @shown_warnings[msg] = true
+      end
+    end
+  end
+
+end

data/lib/jsduck/merger.rb

@@ -66,17 +66,8 @@ module JsDuck
     def create_class(docs, code)
       groups = group_class_docs(docs)
       result = create_bare_class(groups[:class], code)
-      result[:cfg] = groups[:cfg].map { |tags| create_cfg(tags, {}, result[:name]) }
-      result[:method] = []
-      if groups[:constructor].length > 0
-        constr = create_method(groups[:constructor], {})
-        constr[:member] = result[:name]
-        result[:method] << constr
-      end
-      result[:property] = []
-      result[:event] = []
-      result[:css_var] = []
-      result[:css_mixin] = []
+      result[:members] = create_class_members(groups, result[:name])
+      result[:statics] = Class.default_members_hash
       result
     end
 
@@ -114,96 +105,111 @@ module JsDuck
 
     def create_bare_class(docs, code)
       doc_map = build_doc_map(docs)
-      return {
+      return add_shared({
         :tagname => :class,
         :name => detect_name(:class, doc_map, code, :full_name),
         :doc => detect_doc(docs),
         :extends => detect_extends(doc_map, code),
         :mixins => detect_list(:mixins, doc_map, code),
         :alternateClassNames => detect_list(:alternateClassNames, doc_map, code),
-        :xtype => detect_xtype(doc_map),
+        :xtypes => detect_xtypes(doc_map, code),
         :author => detect_author(doc_map),
         :docauthor => detect_docauthor(doc_map),
         :singleton => !!doc_map[:singleton],
-        :private => !!doc_map[:private],
-      }
+        # Used by Aggregator to determine if we're dealing with Ext4 code
+        :code_type => code[:type],
+      }, doc_map)
+    end
+
+    def create_class_members(groups, owner)
+      members = Class.default_members_hash
+      members[:cfg] = groups[:cfg].map { |tags| create_cfg(tags, {}, owner) }
+      if groups[:constructor].length > 0
+        constr = create_method(groups[:constructor], {})
+        constr[:owner] = owner
+        members[:method] << constr
+      end
+      members
     end
 
     def create_method(docs, code)
       doc_map = build_doc_map(docs)
-      return {
+      name = detect_name(:method, doc_map, code)
+      return add_shared({
         :tagname => :method,
-        :name => detect_name(:method, doc_map, code),
-        :member => detect_member(doc_map),
+        :name => name,
+        :owner => detect_owner(doc_map),
         :doc => detect_doc(docs),
         :params => detect_params(docs, code),
-        :return => detect_return(doc_map),
-        :private => !!doc_map[:private],
-        :static => !!doc_map[:static],
-      }
+        :return => detect_return(doc_map, name == "constructor" ? "Object" : "void"),
+      }, doc_map)
     end
 
     def create_event(docs, code)
       doc_map = build_doc_map(docs)
-      return {
+      return add_shared({
         :tagname => :event,
         :name => detect_name(:event, doc_map, code),
-        :member => detect_member(doc_map),
+        :owner => detect_owner(doc_map),
         :doc => detect_doc(docs),
         :params => detect_params(docs, code),
-        :private => !!doc_map[:private],
-      }
+      }, doc_map)
     end
 
-    def create_cfg(docs, code, member = nil)
+    def create_cfg(docs, code, owner = nil)
       doc_map = build_doc_map(docs)
-      return {
+      return add_shared({
         :tagname => :cfg,
         :name => detect_name(:cfg, doc_map, code),
-        :member => detect_member(doc_map) || member,
+        :owner => detect_owner(doc_map) || owner,
         :type => detect_type(:cfg, doc_map, code),
         :doc => detect_doc(docs),
-        :private => !!doc_map[:private],
-      }
+      }, doc_map)
     end
 
     def create_property(docs, code)
       doc_map = build_doc_map(docs)
-      return {
+      return add_shared({
         :tagname => :property,
         :name => detect_name(:property, doc_map, code),
-        :member => detect_member(doc_map),
+        :owner => detect_owner(doc_map),
         :type => detect_type(:property, doc_map, code),
         :doc => detect_doc(docs),
-        :private => !!doc_map[:private],
-        :static => !!doc_map[:static],
-      }
+      }, doc_map)
     end
 
     def create_css_var(docs, code)
       doc_map = build_doc_map(docs)
-      return {
+      return add_shared({
         :tagname => :css_var,
         :name => detect_name(:css_var, doc_map, code),
-        :member => detect_member(doc_map),
+        :owner => detect_owner(doc_map),
         :type => detect_type(:css_var, doc_map, code),
         :doc => detect_doc(docs),
-        :private => !!doc_map[:private],
-        :static => !!doc_map[:static],
-      }
+      }, doc_map)
     end
 
     def create_css_mixin(docs, code)
       doc_map = build_doc_map(docs)
-      return {
+      return add_shared({
         :tagname => :css_mixin,
         :name => detect_name(:css_mixin, doc_map, code),
-        :member => detect_member(doc_map),
+        :owner => detect_owner(doc_map),
         :doc => detect_doc(docs),
         :params => detect_params(docs, code),
+      }, doc_map)
+    end
+
+    # Detects properties common for each doc-object and adds them
+    def add_shared(hash, doc_map)
+      return hash.merge({
         :private => !!doc_map[:private],
+        :protected => !!doc_map[:protected],
         :static => !!doc_map[:static],
-      }
+        :inheritable => !!doc_map[:inheritable],
+        :deprecated => detect_deprecated(doc_map),
+        :alias => doc_map[:alias] ? doc_map[:alias].first : nil,
+      })
     end
 
     def detect_name(tagname, doc_map, code, name_type = :last_name)
@@ -223,7 +229,7 @@ module JsDuck
       end
     end
 
-    def detect_member(doc_map)
+    def detect_owner(doc_map)
       if doc_map[:member]
         doc_map[:member].first[:member]
       else
@@ -258,7 +264,8 @@ module JsDuck
       elsif code[:type] == :assignment && code[:right] && code[:right][:type] == :ext_extend
         code[:right][:extend].join(".")
       elsif code[:type] == :ext_define
-        code[:extend]
+        # Classes defined with Ext.define will automatically inherit from Ext.Base
+        code[:extend] || "Ext.Base"
       end
     end
 
@@ -273,8 +280,14 @@ module JsDuck
       end
     end
 
-    def detect_xtype(doc_map)
-      doc_map[:xtype] ? doc_map[:xtype].first[:name] : nil
+    def detect_xtypes(doc_map, code)
+      if doc_map[:xtype]
+        doc_map[:xtype].map {|tag| tag[:name] }
+      elsif code[:alias]
+        code[:alias].find_all {|a| a =~ /^widget\./ }.map {|a| a.sub(/^widget\./, "") }
+      else
+        []
+      end
     end
 
     def detect_author(doc_map)
@@ -285,12 +298,17 @@ module JsDuck
       doc_map[:docauthor] ? doc_map[:docauthor].first[:name] : nil
     end
 
+    def detect_deprecated(doc_map)
+      doc_map[:deprecated] ? doc_map[:deprecated].first : nil
+    end
+
     def detect_params(docs, code)
       implicit = detect_implicit_params(code)
       explicit = detect_explicit_params(docs)
       # Override implicit parameters with explicit ones
+      # But if explicit ones exist, don't append the implicit ones.
       params = []
-      [implicit.length, explicit.length].max.times do |i|
+      (explicit.length > 0 ? explicit.length : implicit.length).times do |i|
         im = implicit[i] || {}
         ex = explicit[i] || {}
         doc = ex[:doc] || im[:doc] || ""
@@ -319,10 +337,10 @@ module JsDuck
       docs.find_all {|tag| tag[:tagname] == :param}
     end
 
-    def detect_return(doc_map)
+    def detect_return(doc_map, default_type="void")
       ret = doc_map[:return] ? doc_map[:return].first : {}
       return {
-        :type => ret[:type] || "void",
+        :type => ret[:type] || default_type,
         :doc => ret[:doc] || "",
       }
     end

data/lib/jsduck/page.rb

@@ -21,7 +21,7 @@ module JsDuck
       @relations = relations
       @cache = cache
       @formatter = DocFormatter.new
-      @formatter.context = cls.full_name
+      @formatter.class_context = cls.full_name
       @formatter.link_tpl = '<a href="output/%c.html%M" rel="%c%M" class="docClass">%a</a>'
       @formatter.relations = relations
     end