jsduck 2.0.pre4 → 3.0.pre

data/lib/jsduck/merger.rb

@@ -115,7 +115,9 @@ module JsDuck
         :xtypes => detect_xtypes(doc_map, code),
         :author => detect_author(doc_map),
         :docauthor => detect_docauthor(doc_map),
-        :singleton => !!doc_map[:singleton],
+        :singleton => detect_singleton(doc_map, code),
+        :requires => detect_list(:requires, doc_map, code),
+        :uses => detect_list(:uses, doc_map, code),
         # Used by Aggregator to determine if we're dealing with Ext4 code
         :code_type => code[:type],
       }, doc_map)
@@ -141,7 +143,7 @@ module JsDuck
         :owner => detect_owner(doc_map),
         :doc => detect_doc(docs),
         :params => detect_params(docs, code),
-        :return => detect_return(doc_map, name == "constructor" ? "Object" : "void"),
+        :return => detect_return(doc_map, name == "constructor" ? "Object" : "undefined"),
       }, doc_map)
     end
 
@@ -164,6 +166,9 @@ module JsDuck
         :owner => detect_owner(doc_map) || owner,
         :type => detect_type(:cfg, doc_map, code),
         :doc => detect_doc(docs),
+        :optional => detect_optional(:cfg, doc_map),
+        :default => detect_default(:cfg, doc_map, code),
+        :properties => detect_subproperties(docs, :cfg),
       }, doc_map)
     end
 
@@ -175,6 +180,7 @@ module JsDuck
         :owner => detect_owner(doc_map),
         :type => detect_type(:property, doc_map, code),
         :doc => detect_doc(docs),
+        :properties => detect_subproperties(docs, :property),
       }, doc_map)
     end
 
@@ -240,22 +246,21 @@ module JsDuck
     def detect_type(tagname, doc_map, code)
       main_tag = doc_map[tagname] ? doc_map[tagname].first : {}
       if main_tag[:type]
-        main_tag[:type]
+        return main_tag[:type]
       elsif doc_map[:type]
-        doc_map[:type].first[:type]
-      elsif code[:type] == :function
-        "Function"
-      elsif code[:type] == :assignment && code[:right]
-        if code[:right][:type] == :function
-          "Function"
-        elsif code[:right][:type] == :literal
-          code[:right][:class]
-        else
-          "Object"
+        return doc_map[:type].first[:type]
+      elsif code_matches_doc?(tagname, doc_map, code)
+        if code[:type] == :function
+          return "Function"
+        elsif code[:type] == :assignment && code[:right]
+          if code[:right][:type] == :function
+            return "Function"
+          elsif code[:right][:type] == :literal
+            return code[:right][:class]
+          end
         end
-      else
-        "Object"
       end
+      return "Object"
     end
 
     def detect_extends(doc_map, code)
@@ -269,6 +274,28 @@ module JsDuck
       end
     end
 
+    def detect_default(tagname, doc_map, code)
+      main_tag = doc_map[tagname] ? doc_map[tagname].first : {}
+      if main_tag[:default]
+        main_tag[:default]
+      elsif code_matches_doc?(tagname, doc_map, code) && code[:type] == :assignment && code[:right]
+        code[:right][:value]
+      end
+    end
+
+    # True if the name detected from code matches with explicitly documented name.
+    # Also true when no explicit name documented.
+    def code_matches_doc?(tagname, doc_map, code)
+      explicit_name = detect_name(tagname, doc_map, {})
+      implicit_name = detect_name(tagname, {}, code)
+      return explicit_name == "" || explicit_name == implicit_name
+    end
+
+    def detect_optional(tagname, doc_map)
+      main_tag = doc_map[tagname] ? doc_map[tagname].first : {}
+      return main_tag[:optional] != false
+    end
+
     # for detecting mixins and alternateClassNames
     def detect_list(type, doc_map, code)
       if doc_map[type]
@@ -302,6 +329,10 @@ module JsDuck
       doc_map[:deprecated] ? doc_map[:deprecated].first : nil
     end
 
+    def detect_singleton(doc_map, code)
+      !!(doc_map[:singleton] || code[:type] == :ext_define && code[:singleton])
+    end
+
     def detect_params(docs, code)
       implicit = detect_implicit_params(code)
       explicit = detect_explicit_params(docs)
@@ -316,8 +347,9 @@ module JsDuck
           :type => ex[:type] || im[:type] || "Object",
           :name => ex[:name] || im[:name] || "",
           :doc => doc,
-          # convert to boolean for JavaScript export, otherwise it's 0 or nil
-          :optional => !!(doc =~ /\(optional\)/),
+          :optional => ex[:optional] || false,
+          :default => ex[:default],
+          :properties => ex[:properties] || [],
         }
       end
       params
@@ -334,25 +366,63 @@ module JsDuck
     end
 
     def detect_explicit_params(docs)
-      docs.find_all {|tag| tag[:tagname] == :param}
+      combine_properties(docs.find_all {|tag| tag[:tagname] == :param})
+    end
+
+    def detect_subproperties(docs, tagname)
+      prop_docs = docs.find_all {|tag| tag[:tagname] == tagname}
+      prop_docs.length > 0 ? combine_properties(prop_docs)[0][:properties] : []
     end
 
-    def detect_return(doc_map, default_type="void")
+    def combine_properties(raw_items)
+      # First item can't be namespaced, if it is ignore the rest.
+      if raw_items[0] && raw_items[0][:name] =~ /\./
+        return [raw_items[0]]
+      end
+
+      # build name-index of all items
+      index = {}
+      raw_items.each {|it| index[it[:name]] = it }
+
+      # If item name has no dots, add it directly to items array.
+      # Otherwise look up the parent of item and add it as the
+      # property of that parent.
+      items = []
+      raw_items.each do |it|
+        if it[:name] =~ /^(.+)\.([^.]+)$/
+          it[:name] = $2
+          parent = index[$1]
+          parent[:properties] = [] unless parent[:properties]
+          parent[:properties] << it
+        else
+          items << it
+        end
+      end
+      items
+    end
+
+    def detect_return(doc_map, default_type="undefined")
       ret = doc_map[:return] ? doc_map[:return].first : {}
       return {
         :type => ret[:type] || default_type,
+        :name => ret[:name] || "return",
         :doc => ret[:doc] || "",
+        :properties => doc_map[:return] ? detect_subproperties(doc_map[:return], :return) : []
       }
     end
 
     # Combines :doc-s of most tags
-    # Ignores tags that have doc comment themselves
+    # Ignores tags that have doc comment themselves and subproperty tags
     def detect_doc(docs)
       ignore_tags = [:param, :return]
-      doc_tags = docs.find_all { |tag| !ignore_tags.include?(tag[:tagname]) }
+      doc_tags = docs.find_all { |tag| !ignore_tags.include?(tag[:tagname]) && !subproperty?(tag) }
       doc_tags.map { |tag| tag[:doc] }.compact.join(" ")
     end
 
+    def subproperty?(tag)
+      (tag[:tagname] == :cfg || tag[:tagname] == :property) && tag[:name] =~ /\./
+    end
+
     # Build map of at-tags for quick lookup
     def build_doc_map(docs)
       map = {}

data/lib/jsduck/options.rb

@@ -0,0 +1,320 @@
+require 'optparse'
+
+module JsDuck
+
+  # Keeps command line options
+  class Options
+    attr_accessor :input_files
+
+    attr_accessor :output_dir
+    attr_accessor :ignore_global
+    attr_accessor :external_classes
+    attr_accessor :warnings
+    attr_accessor :verbose
+
+    # Customizing output
+    attr_accessor :title
+    attr_accessor :header
+    attr_accessor :footer
+    attr_accessor :head_html
+    attr_accessor :body_html
+    attr_accessor :welcome
+    attr_accessor :guides
+    attr_accessor :videos
+    attr_accessor :examples
+    attr_accessor :categories_path
+    attr_accessor :inline_examples_dir
+    attr_accessor :pretty_json
+    attr_accessor :link_tpl
+    attr_accessor :img_tpl
+    attr_accessor :export
+    attr_accessor :seo
+
+    # Debugging
+    attr_accessor :processes
+    attr_accessor :template_dir
+    attr_accessor :template_links
+    attr_accessor :extjs_path
+    attr_accessor :local_storage_db
+
+    def initialize
+      @input_files = []
+
+      @output_dir = nil
+      @ignore_global = false
+      @external_classes = [
+        # JavaScript builtins
+        "Object",
+        "String",
+        "Number",
+        "Boolean",
+        "RegExp",
+        "Function",
+        "Array",
+        "Arguments",
+        "Date",
+        "Error",
+        # DOM
+        "HTMLElement",
+        "XMLElement",
+        "NodeList",
+        "TextNode",
+        "CSSStyleSheet",
+        "CSSStyleRule",
+        "Event",
+      ]
+
+      @warnings = true
+      @verbose = false
+      @version = "3.0.pre"
+
+      # Customizing output
+      @title = "Sencha Docs - Ext JS"
+      @header = "<strong>Sencha Docs</strong> Ext JS"
+      @footer = 'Generated with <a href="https://github.com/senchalabs/jsduck">JSDuck</a> #{@version}.'
+      @head_html = ""
+      @body_html = ""
+      @welcome = nil
+      @guides = nil
+      @videos = nil
+      @examples = nil
+      @categories_path = nil
+      @inline_examples_dir = nil
+      @pretty_json = false
+      @link_tpl = '<a href="#!/api/%c%-%m" rel="%c%-%m" class="docClass">%a</a>'
+      # Note that we wrap image template inside <p> because {@img} often
+      # appears inline within text, but that just looks ugly in HTML
+      @img_tpl = '<p><img src="doc-resources/%u" alt="%a"></p>'
+      @export = nil
+      @seo = false
+
+      # Debugging
+      @processes = nil
+      @template_dir = File.dirname(File.dirname(File.dirname(__FILE__))) + "/template-min"
+      @template_links = false
+      @extjs_path = "extjs/ext-all.js"
+      @local_storage_db = "docs"
+    end
+
+    def parse!(argv)
+      create_option_parser.parse!(argv).each {|fname| read_filenames(fname) }
+      validate
+    end
+
+    def create_option_parser
+      return OptionParser.new do | opts |
+        opts.banner = "Usage: jsduck [options] files/dirs...\n\n"
+
+        opts.on('-o', '--output=PATH',
+          "Directory to output all this amazing documentation.",
+          "This option MUST be specified.", " ") do |path|
+          @output_dir = path
+        end
+
+        opts.on('--ignore-global', "Turns off the creation of global class.", " ") do
+          @ignore_global = true
+        end
+
+        opts.on('--external=Foo,Bar,Baz', Array,
+          "Declares list of external classes.  These classes",
+          "will then not generate warnings when used in type",
+          "definitions or inherited from.", " ") do |classes|
+          @external_classes += classes
+        end
+
+        opts.on('--no-warnings', "Turns off warnings.", " ") do
+          @warnings = false
+        end
+
+        opts.on('-v', '--verbose', "This will fill up your console.", " ") do
+          @verbose = true
+        end
+
+        opts.separator "Customizing output:"
+        opts.separator ""
+
+        opts.on('--title=TEXT',
+          "Custom title text for the documentation.",
+          "Defaults to 'Sencha Docs - Ext JS'", " ") do |text|
+          @title = text
+          @header = text.sub(/^(.*?) +- +/, "<strong>\\1 </strong>")
+        end
+
+        opts.on('--footer=TEXT',
+          "Custom footer text for the documentation.",
+          "Defaults to: 'Generated with JSDuck.'", " ") do |text|
+          @footer = text
+        end
+
+        opts.on('--head-html=HTML', "HTML to append to the <head> section of index.html.", " ") do |html|
+          @head_html = html
+        end
+
+        opts.on('--body-html=HTML', "HTML to append to the <body> section index.html.", " ") do |html|
+          @body_html = html
+        end
+
+        opts.on('--welcome=PATH',
+          "Path to HTML file with content for welcome page.", " ") do |path|
+          @welcome = path
+        end
+
+        opts.on('--guides=PATH',
+          "Path to JSON file describing the guides. The file",
+          "should be in a dir containing the actual guides.",
+          "A guide is a dir containing README.md, icon.png,",
+          "and other images referenced by the README.md file.", " ") do |path|
+          @guides = path
+        end
+
+        opts.on('--videos=PATH',
+          "Path to JSON file describing the videos.", " ") do |path|
+          @videos = path
+        end
+
+        opts.on('--examples=PATH',
+          "Path JSON file describing the examples.", " ") do |path|
+          @examples = path
+        end
+
+        opts.on('--categories=PATH',
+          "Path to JSON file which defines categories for classes.", " ") do |path|
+          @categories_path = path
+        end
+
+        opts.on('--inline-examples=PATH', "Path to inline examples directory.", " ") do |path|
+          @inline_examples_dir = path
+        end
+
+        opts.on('--pretty-json', "Turn on pretty-printing of JSON.", " ") do
+          @pretty_json = true
+        end
+
+        opts.on('--link=TPL',
+          "HTML template for replacing {@link}.",
+          "Possible placeholders:",
+          "%c - full class name (e.g. 'Ext.Panel')",
+          "%m - class member name prefixed with member type",
+          "     (e.g. 'method-urlEncode')",
+          "%# - inserts '#' if member name present",
+          "%- - inserts '-' if member name present",
+          "%a - anchor text for link",
+          "Default is: '<a href=\"#!/api/%c%-%m\" rel=\"%c%-%m\" class=\"docClass\">%a</a>'", " ") do |tpl|
+          @link_tpl = tpl
+        end
+
+        opts.on('--img=TPL',
+          "HTML template for replacing {@img}.",
+          "Possible placeholders:",
+          "%u - URL from @img tag (e.g. 'some/path.png')",
+          "%a - alt text for image",
+          "Default is: '<p><img src=\"doc-resources/%u\" alt=\"%a\"></p>'", " ") do |tpl|
+          @img_tpl = tpl
+        end
+
+        opts.on('--json', "Produces JSON export instead of HTML documentation.", " ") do
+          @export = :json
+        end
+
+        opts.on('--stdout', "Writes JSON export to STDOUT instead of writing to the filesystem", " ") do
+          @export = :stdout
+        end
+
+        opts.on('--seo', "Creates index.php that handles search engine traffic.", " ") do
+          @seo = true
+        end
+
+        opts.separator "Debugging:"
+        opts.separator ""
+
+        # For debugging it's often useful to set --processes=0 to get deterministic results.
+        opts.on('-p', '--processes=COUNT',
+          "The number of parallel processes to use.",
+          "Defaults to the number of processors/cores.",
+          "Set to 0 to disable parallel processing completely.", " ") do |count|
+          @processes = count.to_i
+        end
+
+        opts.on('--template=PATH',
+          "Directory containing doc-browser UI template.", " ") do |path|
+          @template_dir = path
+        end
+
+        opts.on('--template-links',
+          "Instead of copying template files, create symbolic",
+          "links.  Useful for template files development.",
+          "Only works on platforms supporting symbolic links.", " ") do
+          @template_links = true
+        end
+
+        opts.on('--extjs-path=PATH',
+          "Path for main ExtJS JavaScript file.  Useful for specifying",
+          "something different than extjs/ext.js", " ") do |path|
+          @extjs_path = path
+        end
+
+        opts.on('--local-storage-db=NAME',
+          "Prefix for LocalStorage database names.",
+          "Defaults to 'docs'.", " ") do |name|
+          @local_storage_db = name
+        end
+
+        opts.on('-h', '--help', "Prints this help message", " ") do
+          puts opts
+          exit
+        end
+
+        opts.on('--version', "Prints JSDuck version", " ") do
+          puts "JSDuck " + @version
+          exit
+        end
+      end
+    end
+
+    # scans directory for .js files or simply adds file to input files list
+    def read_filenames(fname)
+      if File.exists?(fname)
+        if File.directory?(fname)
+          Dir[fname+"/**/*.{js,css,scss}"].each {|f| @input_files << f }
+        else
+          @input_files << fname
+        end
+      else
+        $stderr.puts "Warning: File #{fname} not found"
+      end
+    end
+
+    # Runs checks on the options
+    def validate
+      if @input_files.length == 0
+        puts "You should specify some input files, otherwise there's nothing I can do :("
+        exit(1)
+      elsif @export != :stdout
+        if !@output_dir
+          puts "You should also specify an output directory, where I could write all this amazing documentation."
+          exit(1)
+        elsif File.exists?(@output_dir) && !File.directory?(@output_dir)
+          puts "Oh noes!  The output directory is not really a directory at all :("
+          exit(1)
+        elsif !File.exists?(File.dirname(@output_dir))
+          puts "Oh noes!  The parent directory for #{@output_dir} doesn't exist."
+          exit(1)
+        elsif !File.exists?(@template_dir + "/extjs")
+          puts "Oh noes!  The template directory does not contain extjs/ directory :("
+          puts "Please copy ExtJS over to template/extjs or create symlink."
+          puts "For example:"
+          puts "    $ cp -r /path/to/ext-4.0.0 " + @template_dir + "/extjs"
+          exit(1)
+        elsif !File.exists?(@template_dir + "/resources/css")
+          puts "Oh noes!  CSS files for custom ExtJS theme missing :("
+          puts "Please compile SASS files in template/resources/sass with compass."
+          puts "For example:"
+          puts "    $ compass compile " + @template_dir + "/resources/sass"
+          exit(1)
+        end
+      end
+    end
+
+  end
+
+end

data/lib/jsduck/relations.rb

@@ -13,7 +13,7 @@ module JsDuck
 
     def initialize(classes = [], ignorables = [])
       @classes = classes
-      @ignorables = {"Object" => true}
+      @ignorables = {}
       ignorables.each {|classname| @ignorables[classname] = true }
 
       # First build class lookup table; building lookup tables for
@@ -49,6 +49,12 @@ module JsDuck
       @classes.each(&block)
     end
 
+    # Returns list of all classes.  This method allows us to treat
+    # Relations as array and therefore easily mock it
+    def to_a
+      @classes
+    end
+
     def reg_subclasses(cls)
       if !cls.parent
         # do nothing