jsduck 3.4.1 → 3.5.0

data/lib/jsduck/full_exporter.rb

@@ -20,7 +20,12 @@ module JsDuck
       h[:superclasses] = cls.superclasses.collect {|c| c.full_name }
       h[:subclasses] = @relations.subclasses(cls).collect {|c| c.full_name }
       h[:mixedInto] = @relations.mixed_into(cls).collect {|c| c.full_name }
-      h[:allMixins] = cls.all_mixins.collect {|c| c.full_name }
+
+      h[:mixins] = cls.deps(:mixins).collect {|c| c.full_name }
+      h[:parentMixins] = cls.parent_deps(:mixins).collect {|c| c.full_name }
+      h[:requires] = cls.deps(:requires).collect {|c| c.full_name }
+      h[:uses] = cls.deps(:uses).collect {|c| c.full_name }
+
       h
     end
 

data/lib/jsduck/grouped_asset.rb

@@ -0,0 +1,41 @@
+require 'jsduck/logger'
+
+module JsDuck
+
+  # Parent class for assets that consist of groups.
+  # That is: guides, vides, examples.
+  #
+  # Subclasses must initialize @groups before calling any of the
+  # methods in this class.
+  class GroupedAsset
+    # Should be called from constructor after @groups have been read in,
+    # and after it's been ensured that all items in groupes have names.
+    def build_map_by_name(warning_msg)
+      @map_by_name = {}
+      each_item do |item|
+        if @map_by_name[item["name"]]
+          Logger.instance.warn(nil, "#{warning_msg} '#{item['name']}'")
+        end
+        @map_by_name[item["name"]] = item
+      end
+    end
+
+    # Accesses item by name
+    def [](name)
+      @map_by_name[name]
+    end
+
+    # Iterates over all items in all groups
+    def each_item
+      @groups.each do |group|
+        group["items"].each {|item| yield item }
+      end
+    end
+
+    # Returns all groups as array
+    def to_array
+      @groups
+    end
+  end
+
+end

data/lib/jsduck/guides.rb

@@ -1,35 +1,38 @@
 require 'jsduck/logger'
 require 'jsduck/json_duck'
 require 'jsduck/null_object'
+require 'jsduck/logger'
+require 'jsduck/grouped_asset'
 require 'fileutils'
 
 module JsDuck
 
   # Reads in guides and converts them to JsonP files
-  class Guides
+  class Guides < GroupedAsset
     # Creates Guides object from filename and formatter
     def self.create(filename, formatter)
       if filename
         Guides.new(filename, formatter)
       else
-        NullObject.new(:to_array => [], :to_html => "")
+        NullObject.new(:to_array => [], :to_html => "", :[] => nil)
       end
     end
 
     # Parses guides config file
     def initialize(filename, formatter)
       @path = File.dirname(filename)
-      @guides = JsonDuck.read(filename)
+      @groups = JsonDuck.read(filename)
+      build_map_by_name("Two guides have the same name")
       @formatter = formatter
     end
 
     # Writes all guides to given dir in JsonP format
     def write(dir)
       FileUtils.mkdir(dir) unless File.exists?(dir)
-      @guides.each {|group| group["items"].each {|g| write_guide(g, dir) } }
+      each_item {|guide| write_guide(guide, dir) }
       # Write the JSON to output dir, so it's available in released
       # version of docs and people can use it with JSDuck by themselves.
-      JsonDuck.write_json(dir+"/guides.json", @guides)
+      JsonDuck.write_json(dir+"/guides.json", @groups)
     end
 
     def write_guide(guide, dir)
@@ -63,8 +66,9 @@ module JsDuck
     # 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",
-        "<ul class='toc'>\n",
+        "<ol>\n",
       ]
       new_html = []
       i = 0
@@ -77,20 +81,20 @@ module JsDuck
           new_html << line
         end
       end
-      toc << "</ul>\n"
-      # Inject TOC at below first heading
-      new_html.insert(1, toc)
-      new_html.flatten.join
-    end
-
-    # Returns all guides as array
-    def to_array
-      @guides
+      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
-      html = @guides.map do |group|
+      html = @groups.map do |group|
         [
           "<h3>#{group['title']}</h3>",
           "<ul>",
@@ -105,6 +109,12 @@ module JsDuck
         </div>
       EOHTML
     end
+
+    # Extracts guide icon URL from guide hash
+    def icon_url(guide)
+      "guides/" + guide["name"] + "/icon-lg.png"
+    end
+
   end
 
 end

data/lib/jsduck/index_html.rb

@@ -5,11 +5,8 @@ module JsDuck
 
   # Deals with creation of main HTML or PHP files.
   class IndexHtml
-    attr_accessor :welcome
-    attr_accessor :categories
-    attr_accessor :guides
-
-    def initialize(opts)
+    def initialize(assets, opts)
+      @assets = assets
       @opts = opts
     end
 
@@ -34,9 +31,9 @@ module JsDuck
         "{header}" => @opts.header,
         "{footer}" => "<div id='footer-content' style='display: none'>#{@opts.footer}</div>",
         "{extjs_path}" => @opts.extjs_path,
-        "{welcome}" => @welcome.to_html,
-        "{categories}" => @categories.to_html,
-        "{guides}" => @guides.to_html,
+        "{welcome}" => @assets.welcome.to_html,
+        "{categories}" => @assets.categories.to_html,
+        "{guides}" => @assets.guides.to_html,
         "{head_html}" => @opts.head_html,
         "{body_html}" => @opts.body_html,
       })

data/lib/jsduck/lexer.rb

@@ -140,7 +140,7 @@ module JsDuck
         elsif @input.check(/\//)
           # Several things begin with dash:
           # - comments, regexes, division-operators
-          if @input.check(/\/\*\*/)
+          if @input.check(/\/\*\*[^\/]/)
             return {
               :type => :doc_comment,
               # Calculate current line number, starting with 1

data/lib/jsduck/logger.rb

@@ -15,7 +15,7 @@ module JsDuck
       @warning_docs = [
         [:global, "Member doesn't belong to any class"],
         [:inheritdoc, "@inheritdoc referring to unknown class or member"],
-        [:extend, "@extend or @mixin referring to unknown class"],
+        [:extend, "@extend/mixin/requires/uses referring to unknown class"],
         [:link, "{@link} to unknown class or member"],
         [:link_ambiguous, "{@link} is ambiguous"],
         [:link_auto, "Auto-detected link to unknown class or member"],
@@ -37,6 +37,7 @@ module JsDuck
         [:cat_no_match, "Class pattern in categories file matches nothing"],
         [:cat_class_missing, "Class is missing from categories file"],
         [:guide, "Guide is missing from --guides dir"],
+        [:aside, "Problem with @aside tag"],
       ]
       # Turn off all warnings by default.
       # This is good for testing.
@@ -66,7 +67,7 @@ module JsDuck
       elsif @warnings.has_key?(type)
         @warnings[type] = enabled
       else
-        warn(nil, "Warning of type '#{type} doesn't exist")
+        warn(nil, "Warning of type '#{type}' doesn't exist")
       end
     end
 

data/lib/jsduck/merger.rb

@@ -290,14 +290,16 @@ module JsDuck
     def detect_extends(doc_map, code)
       if doc_map[:extends]
         cls = doc_map[:extends].first[:extends]
-        # Ignore extending of the Object class
-        cls == "Object" ? nil : cls
       elsif code[:type] == :assignment && code[:right] && code[:right][:type] == :ext_extend
-        code[:right][:extend].join(".")
+        cls = code[:right][:extend].join(".")
       elsif code[:type] == :ext_define
         # Classes defined with Ext.define will automatically inherit from Ext.Base
-        code[:extend] || "Ext.Base"
+        cls = code[:extend] || "Ext.Base"
+      else
+        cls = nil
       end
+      # Ignore extending of the Object class
+      cls == "Object" ? nil : cls
     end
 
     def detect_default(tagname, doc_map, code)
@@ -348,7 +350,7 @@ module JsDuck
     # it instead of creating a new hash.
     def build_aliases_hash(aliases, hash={})
       aliases.each do |a|
-        if a =~ /^(.+)\.([^.]+)$/
+        if a =~ /^([^.]+)\.(.+)$/
           if hash[$1]
             hash[$1] << $2
           else

data/lib/jsduck/meta_tag.rb

@@ -26,12 +26,20 @@ module JsDuck
     # existance of the tag.
     attr_reader :boolean
 
+    # Whether to render the tag before other content (:top) or after
+    # it (:bottom).  Defaults to :bottom.
+    attr_accessor :position
+
     # Here the appropriate class or member will be injected,
     # so the to_value and to_html methods can for produce
     # different output based on whether the tag is inside class,
     # method, event, etc.
     attr_accessor :context
 
+    # Here the Assets object will be injected, so the Tag implementation
+    # can access guides, videos, etc when he needs to.
+    attr_accessor :assets
+
     # It gets passed an array of contents gathered from all meta-tags
     # of given type. It should return the value to be stored for this
     # meta-tag at :key. The returned value is also passed to #to_html

data/lib/jsduck/meta_tag_loader.rb

@@ -55,9 +55,11 @@ module JsDuck
 
     # Instanciates tag class.
     # When .key is missing, creates it from .name
+    # When .position is missing, defaults to :bottom
     def create_tag(cls)
       tag = cls.new
       tag.key = tag.name.to_sym unless tag.key
+      tag.position = :bottom unless tag.position
       tag
     end
   end

data/lib/jsduck/meta_tag_registry.rb

@@ -31,9 +31,10 @@ module JsDuck
       register_keys
     end
 
-    # Returns array of all available tag instances
-    def tags
-      @tags
+    # Returns array of all available tag instances.
+    # When position provided, returns only tags in that position
+    def tags(position=nil)
+      position ? @tags.find_all {|t| t.position == position} : @tags
     end
 
     # Accesses tag by key or name
@@ -52,6 +53,11 @@ module JsDuck
       @tags.each {|tag| tag.formatter = doc_formatter }
     end
 
+    # Gives access to assets for all tags
+    def assets=(assets)
+      @tags.each {|tag| tag.assets = assets }
+    end
+
     # Returns array of attributes to be shown in member signatures
     # (and in order they should be shown in).
     def signatures

data/lib/jsduck/options.rb

@@ -31,6 +31,7 @@ module JsDuck
     attr_accessor :export
     attr_accessor :seo
     attr_accessor :eg_iframe
+    attr_accessor :examples_base_url
 
     # Debugging
     attr_accessor :processes
@@ -71,7 +72,7 @@ module JsDuck
       ]
       @meta_tag_paths = []
 
-      @version = "3.4.1"
+      @version = "3.5.0"
 
       # Customizing output
       @title = "Sencha Docs - Ext JS"
@@ -94,6 +95,7 @@ module JsDuck
       @export = nil
       @seo = false
       @eg_iframe = nil
+      @examples_base_url = "extjs/examples/"
 
       # Debugging
       # Turn multiprocessing off by default in Windows
@@ -276,6 +278,11 @@ module JsDuck
           @eg_iframe = canonical(path)
         end
 
+        opts.on('--examples-base-url=URL',
+          "Base URL for examples with relative URL-s.", " ") do |path|
+          @examples_base_url = path
+        end
+
         opts.separator "Debugging:"
         opts.separator ""
 
@@ -428,7 +435,7 @@ module JsDuck
         if File.directory?(fname)
           Dir[fname+"/**/*.{js,css,scss}"].each {|f| @input_files << f }
         elsif fname =~ /\.jsb3$/
-          @input_files += extract_jsb_files(fname)
+          extract_jsb_files(fname).each {|fn| read_filenames(fn) }
         else
           @input_files << fname
         end

data/lib/jsduck/renderer.rb

@@ -13,12 +13,13 @@ module JsDuck
           "<div>",
             render_sidebar,
             "<div class='doc-contents'>",
+              render_meta_data(@cls[:html_meta], :top),
               render_private_class_notice,
               @cls[:doc],
-              render_meta_data(@cls[:html_meta]),
+              render_meta_data(@cls[:html_meta], :bottom),
             "</div>",
             "<div class='members'>",
-              render_member_sections,
+              render_all_sections,
             "</div>",
           "</div>",
         ].flatten.compact.join
@@ -33,18 +34,21 @@ module JsDuck
       ]
     end
 
-    def render_meta_data(meta_data)
+    def render_meta_data(meta_data, position)
       return if meta_data.size == 0
 
-      MetaTagRegistry.instance.tags.map {|tag| meta_data[tag.key] }
+      MetaTagRegistry.instance.tags(position).map {|tag| meta_data[tag.key] }
     end
 
     def render_sidebar
       items = [
         render_alternate_class_names,
         render_tree,
-        render_dependencies(:allMixins, "Mixins"),
+        render_dependencies(:mixins, "Mixins"),
+        render_dependencies(:parentMixins, "Inherited mixins"),
         render_dependencies(:requires, "Requires"),
+        render_dependencies(:subclasses, "Subclasses"),
+        render_dependencies(:mixedInto, "Mixed into"),
         render_dependencies(:uses, "Uses"),
         render_files,
       ]
@@ -59,7 +63,7 @@ module JsDuck
       return if @cls[:alternateClassNames].length == 0
       return [
         "<h4>Alternate names</h4>",
-        @cls[:alternateClassNames].map {|name| "<div class='alternate-class-name'>#{name}</div>" },
+        @cls[:alternateClassNames].sort.map {|name| "<div class='alternate-class-name'>#{name}</div>" },
       ]
     end
 
@@ -67,7 +71,7 @@ module JsDuck
       return if !@cls[type] || @cls[type].length == 0
       return [
         "<h4>#{title}</h4>",
-        @cls[type].map {|name| "<div class='dependency'>#{render_link(name)}</div>" },
+        @cls[type].sort.map {|name| "<div class='dependency'>#{name.exists? ? render_link(name) : name}</div>" },
       ]
     end
 
@@ -88,23 +92,21 @@ module JsDuck
     # We still create the tree, but without links in it.
     def render_tree
       return if !@cls[:extends] || @cls[:extends] == "Object"
-      tree = ["<h4>Hierarchy</h4>"]
 
-      if @cls[:superclasses].length > 0
-        tree + render_class_tree(@cls[:superclasses].concat([@cls[:name]]), {:first => true, :links => true})
-      else
-        tree + render_class_tree([@cls[:extends], @cls[:name]], {:first => true})
-      end
+      return [
+        "<h4>Hierarchy</h4>",
+        render_class_tree(@cls[:superclasses] + [@cls[:name]])
+      ]
     end
 
-    def render_class_tree(superclasses, o)
-      return "" if superclasses.length == 0
+    def render_class_tree(classes, i=0)
+      return "" if classes.length <= i
 
-      name = superclasses[0]
+      name = classes[i]
       return [
-        "<div class='subclass #{o[:first] ? 'first-child' : ''}'>",
-          superclasses.length > 1 ? (o[:links] ? render_link(name) : name) : "<strong>#{name}</strong>",
-          render_class_tree(superclasses.slice(1, superclasses.length-1), {:links => o[:links]}),
+        "<div class='subclass #{i == 0 ? 'first-child' : ''}'>",
+          classes.length-1 == i ? "<strong>#{name}</strong>" : (name.exists? ? render_link(name) : name),
+          render_class_tree(classes, i+1),
         "</div>",
       ]
     end
@@ -115,9 +117,8 @@ module JsDuck
       return "<a href='#!/api/#{id}' rel='#{id}' class='docClass'>#{label}</a>"
     end
 
-    def render_member_sections
+    def render_all_sections
       sections = [
-        {:type => :cfg, :title => "Config options"},
         {:type => :property, :title => "Properties"},
         {:type => :method, :title => "Methods"},
         {:type => :event, :title => "Events"},
@@ -125,22 +126,43 @@ module JsDuck
         {:type => :css_mixin, :title => "CSS Mixins"},
       ]
 
+      render_configs_section + sections.map {|sec| render_section(sec) }
+    end
+
+    def render_configs_section
+      configs = @cls[:members][:cfg] + @cls[:statics][:cfg]
+
+      if configs.length > 0
+        required, optional = configs.partition {|c| c[:meta][:required] }
+        return [
+          "<div class='members-section'>",
+            required.length == 0 ? "<div class='definedBy'>Defined By</div>" : "",
+            "<h3 class='members-title icon-cfg'>Config options</h3>",
+            render_subsection(required, "Required Config options"),
+            render_subsection(optional, required.length > 0 ? "Optional Config options" : nil),
+          "</div>",
+        ]
+      else
+        return []
+      end
+    end
+
+    def render_section(sec)
+      members = @cls[:members][sec[:type]]
+      statics = @cls[:statics][sec[:type]]
+
       # Skip rendering empty sections
-      sections.map do |sec|
-        members = @cls[:members][sec[:type]]
-        statics = @cls[:statics][sec[:type]]
-        if members.length > 0 || statics.length > 0
-          [
-            "<div class='members-section'>",
-              statics.length == 0 ? "<div class='definedBy'>Defined By</div>" : "",
-              "<h3 class='members-title icon-#{sec[:type]}'>#{sec[:title]}</h3>",
-              render_subsection(members, statics.length > 0 ? "Instance #{sec[:title]}" : nil),
-              render_subsection(statics, "Static #{sec[:title]}"),
-            "</div>",
-          ]
-        else
-          nil
-        end
+      if members.length > 0 || statics.length > 0
+        return [
+          "<div class='members-section'>",
+            statics.length == 0 ? "<div class='definedBy'>Defined By</div>" : "",
+            "<h3 class='members-title icon-#{sec[:type]}'>#{sec[:title]}</h3>",
+            render_subsection(members, statics.length > 0 ? "Instance #{sec[:title]}" : nil),
+            render_subsection(statics, "Static #{sec[:title]}"),
+          "</div>",
+        ]
+      else
+        return []
       end
     end
 
@@ -236,13 +258,17 @@ module JsDuck
     end
 
     def render_long_doc(m)
-      doc = [m[:doc]]
+      doc = []
+
+      doc << render_meta_data(m[:html_meta], :top)
+
+      doc << m[:doc]
 
       if m[:default] && m[:default] != "undefined"
         doc << "<p>Defaults to: <code>" + CGI.escapeHTML(m[:default]) + "</code></p>"
       end
 
-      doc << render_meta_data(m[:html_meta])
+      doc << render_meta_data(m[:html_meta], :bottom)
 
       doc << render_params_and_return(m)