jsduck 3.0.pre → 3.0.pre2

data/lib/jsduck/merger.rb

@@ -113,8 +113,7 @@ module JsDuck
         :mixins => detect_list(:mixins, doc_map, code),
         :alternateClassNames => detect_list(:alternateClassNames, doc_map, code),
         :xtypes => detect_xtypes(doc_map, code),
-        :author => detect_author(doc_map),
-        :docauthor => detect_docauthor(doc_map),
+        :meta => detect_meta(doc_map),
         :singleton => detect_singleton(doc_map, code),
         :requires => detect_list(:requires, doc_map, code),
         :uses => detect_list(:uses, doc_map, code),
@@ -144,6 +143,7 @@ module JsDuck
         :doc => detect_doc(docs),
         :params => detect_params(docs, code),
         :return => detect_return(doc_map, name == "constructor" ? "Object" : "undefined"),
+        :template => !!doc_map[:template],
       }, doc_map)
     end
 
@@ -166,9 +166,10 @@ 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),
+        :required => detect_required(:cfg, doc_map),
         :default => detect_default(:cfg, doc_map, code),
         :properties => detect_subproperties(docs, :cfg),
+        :accessor => !!doc_map[:accessor],
       }, doc_map)
     end
 
@@ -208,7 +209,7 @@ module JsDuck
 
     # Detects properties common for each doc-object and adds them
     def add_shared(hash, doc_map)
-      return hash.merge({
+      hash.merge!({
         :private => !!doc_map[:private],
         :protected => !!doc_map[:protected],
         :static => !!doc_map[:static],
@@ -216,6 +217,12 @@ module JsDuck
         :deprecated => detect_deprecated(doc_map),
         :alias => doc_map[:alias] ? doc_map[:alias].first : nil,
       })
+      hash[:id] = create_member_id(hash)
+      return hash
+    end
+
+    def create_member_id(m)
+      "#{m[:static] ? 'static-' : ''}#{m[:tagname]}-#{m[:name]}"
     end
 
     def detect_name(tagname, doc_map, code, name_type = :last_name)
@@ -265,7 +272,9 @@ module JsDuck
 
     def detect_extends(doc_map, code)
       if doc_map[:extends]
-        doc_map[:extends].first[: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(".")
       elsif code[:type] == :ext_define
@@ -291,9 +300,9 @@ module JsDuck
       return explicit_name == "" || explicit_name == implicit_name
     end
 
-    def detect_optional(tagname, doc_map)
+    def detect_required(tagname, doc_map)
       main_tag = doc_map[tagname] ? doc_map[tagname].first : {}
-      return main_tag[:optional] != false
+      return main_tag[:optional] == false
     end
 
     # for detecting mixins and alternateClassNames
@@ -309,20 +318,26 @@ module JsDuck
 
     def detect_xtypes(doc_map, code)
       if doc_map[:xtype]
-        doc_map[:xtype].map {|tag| tag[:name] }
+        {"widget" => doc_map[:xtype].map {|tag| tag[:name] } }
       elsif code[:alias]
-        code[:alias].find_all {|a| a =~ /^widget\./ }.map {|a| a.sub(/^widget\./, "") }
+        xtypes = {}
+        code[:alias].each do |a|
+          if a =~ /^(\w+)\.(\w+)$/
+            if xtypes[$1]
+              xtypes[$1] << $2
+            else
+              xtypes[$1] = [$2]
+            end
+          end
+        end
+        xtypes
       else
-        []
+        {}
       end
     end
 
-    def detect_author(doc_map)
-      doc_map[:author] ? doc_map[:author].first[:name] : nil
-    end
-
-    def detect_docauthor(doc_map)
-      doc_map[:docauthor] ? doc_map[:docauthor].first[:name] : nil
+    def detect_meta(doc_map)
+      doc_map[:meta] ? doc_map[:meta].map {|tag| {:name => tag[:name], :content => tag[:content]} } : []
     end
 
     def detect_deprecated(doc_map)

data/lib/jsduck/options.rb

@@ -9,6 +9,7 @@ module JsDuck
     attr_accessor :output_dir
     attr_accessor :ignore_global
     attr_accessor :external_classes
+    attr_accessor :meta_tags
     attr_accessor :warnings
     attr_accessor :verbose
 
@@ -36,6 +37,7 @@ module JsDuck
     attr_accessor :template_links
     attr_accessor :extjs_path
     attr_accessor :local_storage_db
+    attr_accessor :ext_namespaces
 
     def initialize
       @input_files = []
@@ -63,15 +65,19 @@ module JsDuck
         "CSSStyleRule",
         "Event",
       ]
+      @meta_tags = [
+        {:name => "author", :title => "Author", :strip => / *<.*?> */},
+        {:name => "docauthor", :title => "Documentation author", :strip => / *<.*?> */},
+      ]
 
       @warnings = true
       @verbose = false
-      @version = "3.0.pre"
+      @version = "3.0.pre2"
 
       # 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}.'
+      @footer = "Generated with <a href='https://github.com/senchalabs/jsduck'>JSDuck</a> #{@version}."
       @head_html = ""
       @body_html = ""
       @welcome = nil
@@ -90,10 +96,18 @@ module JsDuck
 
       # Debugging
       @processes = nil
-      @template_dir = File.dirname(File.dirname(File.dirname(__FILE__))) + "/template-min"
+      @root_dir = File.dirname(File.dirname(File.dirname(__FILE__)))
+      @template_dir = @root_dir + "/template-min"
       @template_links = false
       @extjs_path = "extjs/ext-all.js"
       @local_storage_db = "docs"
+      @ext_namespaces = ["Ext"]
+    end
+
+    # Make options object behave like hash.
+    # This allows us to substitute it with hash in unit tests.
+    def [](key)
+      send(key)
     end
 
     def parse!(argv)
@@ -107,8 +121,8 @@ module JsDuck
 
         opts.on('-o', '--output=PATH',
           "Directory to output all this amazing documentation.",
-          "This option MUST be specified.", " ") do |path|
-          @output_dir = path
+          "This option MUST be specified (unless --stdout).", " ") do |path|
+          @output_dir = canonical(path)
         end
 
         opts.on('--ignore-global', "Turns off the creation of global class.", " ") do
@@ -122,6 +136,20 @@ module JsDuck
           @external_classes += classes
         end
 
+        opts.on('--builtin-classes',
+          "Includes docs for JavaScript builtin classes.", " ") do
+          read_filenames(@root_dir + "/js-classes")
+        end
+
+        opts.on('--meta-tags @name=Title,...', Array,
+          "Defines custom meta-data tags in addition to",
+          "@author and @docauthor.  Experimantal!", " ") do |tags|
+          tags.each do |t|
+            t = t.split(/=/)
+            @meta_tags << {:name => t[0].sub(/^@/, ""), :title => t[1]}
+          end
+        end
+
         opts.on('--no-warnings', "Turns off warnings.", " ") do
           @warnings = false
         end
@@ -156,7 +184,7 @@ module JsDuck
 
         opts.on('--welcome=PATH',
           "Path to HTML file with content for welcome page.", " ") do |path|
-          @welcome = path
+          @welcome = canonical(path)
         end
 
         opts.on('--guides=PATH',
@@ -164,26 +192,26 @@ module JsDuck
           "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
+          @guides = canonical(path)
         end
 
         opts.on('--videos=PATH',
           "Path to JSON file describing the videos.", " ") do |path|
-          @videos = path
+          @videos = canonical(path)
         end
 
         opts.on('--examples=PATH',
           "Path JSON file describing the examples.", " ") do |path|
-          @examples = path
+          @examples = canonical(path)
         end
 
         opts.on('--categories=PATH',
           "Path to JSON file which defines categories for classes.", " ") do |path|
-          @categories_path = path
+          @categories_path = canonical(path)
         end
 
         opts.on('--inline-examples=PATH', "Path to inline examples directory.", " ") do |path|
-          @inline_examples_dir = path
+          @inline_examples_dir = canonical(path)
         end
 
         opts.on('--pretty-json', "Turn on pretty-printing of JSON.", " ") do
@@ -237,7 +265,7 @@ module JsDuck
 
         opts.on('--template=PATH',
           "Directory containing doc-browser UI template.", " ") do |path|
-          @template_dir = path
+          @template_dir = canonical(path)
         end
 
         opts.on('--template-links',
@@ -250,7 +278,7 @@ module JsDuck
         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
+          @extjs_path = path # NB! must be relative path
         end
 
         opts.on('--local-storage-db=NAME',
@@ -259,8 +287,49 @@ module JsDuck
           @local_storage_db = name
         end
 
-        opts.on('-h', '--help', "Prints this help message", " ") do
-          puts opts
+        opts.on('--ext-namespaces=Ext,Foo', Array,
+          "Namespace(s) of ExtJS. Defaults to 'Ext'.", " ") do |ns|
+          @ext_namespaces = ns
+        end
+
+        opts.on('-h', '--help[=full]',
+          "Short help or --help=full for all available options.", " ") do |v|
+          if v == 'full'
+            puts opts
+          else
+            puts opts.banner
+            puts "For example:"
+            puts
+            puts "    # Documentation for builtin JavaScript classes like Array and String"
+            puts "    jsduck --output output/dir  --builtin-classes"
+            puts
+            puts "    # Documentation for your own JavaScript"
+            puts "    jsduck --output output/dir  input-file.js some/input/dir"
+            puts
+            puts "The main options:"
+            puts
+
+            show_help = false
+            main_opts = [
+              /--output/,
+              /--builtin-classes/,
+              /--no-warnings/,
+              /--verbose/,
+              /--help/,
+              /--version/,
+            ]
+            opts.summarize([], opts.summary_width) do |helpline|
+              if main_opts.any? {|re| helpline =~ re }
+                puts helpline
+                show_help = true
+              elsif helpline =~ /^\s*$/ && show_help == true
+                puts helpline
+                show_help = false
+              elsif show_help == true
+                puts helpline
+              end
+            end
+          end
           exit
         end
 
@@ -284,6 +353,15 @@ module JsDuck
       end
     end
 
+    # Converts relative path to full path
+    #
+    # Especially important for running on Windows where C:\foo\bar
+    # pathnames are converted to C:/foo/bar which ruby can work on
+    # more easily.
+    def canonical(path)
+      File.expand_path(path)
+    end
+
     # Runs checks on the options
     def validate
       if @input_files.length == 0

data/lib/jsduck/renderer.rb

@@ -5,6 +5,10 @@ module JsDuck
   # Ruby-side implementation of class docs Renderer.
   # Uses PhantomJS to run Docs.Renderer JavaScript.
   class Renderer
+    def initialize(options={})
+      @options = options
+    end
+
     def render(cls)
         @cls = cls
 
@@ -14,6 +18,7 @@ module JsDuck
             "<div class='doc-contents'>",
               render_private_class_notice,
               @cls[:doc],
+              render_meta_data,
             "</div>",
             "<div class='members'>",
               render_member_sections,
@@ -31,6 +36,25 @@ module JsDuck
       ]
     end
 
+    def render_meta_data
+      return if !@cls[:meta] || @cls[:meta].length == 0
+
+      html = ["<ul class='meta-data'>"]
+
+      @options[:meta_tags].each do |meta|
+        title = meta[:title]
+        items = @cls[:meta].find_all {|m| m[:name] == meta[:name]}.map {|m| m[:content] }
+        content = meta[:strip] ? items.map {|m| m.gsub(meta[:strip], "") } : items
+        if items.length > 0
+          html << "<li><strong>#{CGI.escapeHTML(title)}:</strong> #{CGI.escapeHTML(content.join(', '))}</li>"
+        end
+      end
+
+      html << "</ul>"
+
+      html
+    end
+
     def render_hierarchy
       has_parents = @cls[:extends] && @cls[:extends] != "Object"
       has_alt_names = @cls[:alternateClassNames].length > 0
@@ -144,7 +168,7 @@ module JsDuck
       inherited = owner == @cls[:name] ? "not-inherited" : "inherited"
 
       return [
-        "<div id='#{m[:tagname]}-#{m[:name]}' class='member #{first_child} #{inherited}'>",
+        "<div id='#{m[:id]}' class='member #{first_child} #{inherited}'>",
           # leftmost column: expand button
           "<a href='#' class='side #{expandable}'>",
             "<span>&nbsp;</span>",
@@ -201,11 +225,14 @@ module JsDuck
       if m[:deprecated]
         after += "<strong class='deprecated-signature'>deprecated</strong>"
       end
-      if m[:tagname] == :cfg && !m[:optional]
+      if m[:required]
         after += "<strong class='required-signature'>required</strong>"
       end
+      if m[:template]
+        after += "<strong class='template-signature'>template</strong>"
+      end
 
-      uri = "#!/api/#{m[:owner]}-#{m[:tagname]}-#{m[:name]}"
+      uri = "#!/api/#{m[:owner]}-#{m[:id]}"
 
       return [
         before,
@@ -237,6 +264,15 @@ module JsDuck
         ]
       end
 
+      if m[:template]
+        doc << [
+          "<div class='template'>",
+          "<p>This is a template method. A hook into the functionality of this class.",
+          "Feel free to override it in child classes.</p>",
+          "</div>",
+        ]
+      end
+
       doc << render_params_and_return(m)
 
       doc
@@ -297,6 +333,7 @@ module JsDuck
     end
 
     def render_return(ret)
+      return if ret[:type] == "undefined"
       return [
         "<h3 class='pa'>Returns</h3>",
         "<ul>",

data/lib/jsduck/search_data.rb

@@ -10,11 +10,13 @@ module JsDuck
       list = []
       docs.each do |cls|
         list << class_node(cls)
-        [:cfg, :property, :method, :event].each do |type|
-          cls.members(type).each do |m|
-            # skip inherited items and constructors
-            if m[:owner] == cls.full_name && m[:name] != cls.short_name
-              list << member_node(m, cls)
+        [:members, :statics].each do |group|
+          [:cfg, :property, :method, :event].each do |type|
+            cls.members(type, group).each do |m|
+              # skip inherited items and constructors
+              if m[:owner] == cls.full_name && m[:name] != cls.short_name
+                list << member_node(m, cls)
+              end
             end
           end
         end
@@ -38,6 +40,7 @@ module JsDuck
         :cls => cls.full_name,
         :member => member[:name],
         :type => member[:tagname],
+        :id => member[:id],
       }
     end
 

data/lib/jsduck/source_file.rb

@@ -15,9 +15,10 @@ module JsDuck
     attr_reader :docs
     attr_reader :html_filename
 
-    def initialize(contents, filename="")
+    def initialize(contents, filename="", options={})
       @contents = contents
       @filename = filename
+      @options = options
       @html_filename = ""
       @links = {}
 
@@ -69,7 +70,7 @@ module JsDuck
       else
         # when creation of global class is skipped,
         # this owner property can be nil.
-        (doc[:owner] || "global").gsub(/\./, '-') + "-" + doc[:tagname].to_s + "-" + doc[:name]
+        (doc[:owner] || "global").gsub(/\./, '-') + "-" + doc[:id]
       end
     end
 
@@ -78,9 +79,9 @@ module JsDuck
     # Parses the file depending on filename as JS or CSS
     def parse
       if @filename =~ /\.s?css$/
-        CssParser.new(@contents).parse
+        CssParser.new(@contents, @options).parse
       else
-        JsParser.new(@contents).parse
+        JsParser.new(@contents, @options).parse
       end
     end