jsduck 3.0.pre → 3.0.pre2

data/jsduck.gemspec

@@ -2,8 +2,8 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = ">= 1.3.7"
 
   s.name = 'jsduck'
-  s.version = '3.0.pre'
-  s.date = '2011-09-08'
+  s.version = '3.0.pre2'
+  s.date = '2011-09-20'
   s.summary = "Simple JavaScript Duckumentation generator"
   s.description = "Documentation generator for ExtJS 4"
   s.homepage = "https://github.com/senchalabs/jsduck"

data/lib/jsduck/accessors.rb

@@ -0,0 +1,71 @@
+require 'jsduck/logger'
+
+module JsDuck
+
+  class Accessors
+    # Given a class, generates accessor methods to configs with
+    # @accessor tag.  Modifies the class by adding these methods.
+    # When class already contains a getter or setter, the method is
+    # not added.
+    def create(cls)
+      # Grab all configs tagged as @accessor
+      accessors = cls[:members][:cfg].find_all {|cfg| cfg[:accessor] }
+
+      # Build lookup table of method names
+      methods = {}
+      cls[:members][:method].each do |m|
+        methods[m[:name]] = m;
+      end
+
+      accessors.each do |cfg|
+        # add getter if no method with same name exists
+        get = create_getter(cfg)
+        if !methods[get[:name]]
+          cls[:members][:method] << get
+        end
+        # add setter if no method with same name exists
+        set = create_setter(cfg)
+        if !methods[set[:name]]
+          cls[:members][:method] << set
+        end
+      end
+    end
+
+    def create_getter(cfg)
+      return {
+        :tagname => :method,
+        :name => "get" + upcase_first(cfg[:name]),
+        :doc => "Returns the value of {@link #cfg-#{cfg[:name]}}.",
+        :params => [],
+        :return => {
+          :type => cfg[:type],
+          :doc => "",
+        },
+        :owner => cfg[:owner],
+      }
+    end
+
+    def create_setter(cfg)
+      return {
+        :tagname => :method,
+        :name => "set" + upcase_first(cfg[:name]),
+        :doc => "Sets the value of {@link #cfg-#{cfg[:name]}}.",
+        :params => [{
+            :type => cfg[:type],
+            :name => cfg[:name],
+            :doc => "",
+          }],
+        :return => {
+          :type => "undefined",
+          :doc => "",
+        },
+        :owner => cfg[:owner],
+      }
+    end
+
+    def upcase_first(str)
+      str[0,1].upcase + str[1..-1]
+    end
+  end
+
+end

data/lib/jsduck/aggregator.rb

@@ -1,4 +1,5 @@
 require 'jsduck/class'
+require 'jsduck/accessors'
 
 module JsDuck
 
@@ -50,12 +51,15 @@ module JsDuck
 
     # Merges new class-doc into old one.
     def merge_classes(old, new)
-      [:extends, :xtype, :singleton, :private, :protected].each do |tag|
+      [:extends, :singleton, :private, :protected].each do |tag|
         old[tag] = old[tag] || new[tag]
       end
-      [:mixins, :alternateClassNames, :xtypes].each do |tag|
+      [:mixins, :alternateClassNames].each do |tag|
         old[tag] = old[tag] + new[tag]
       end
+      new[:xtypes].each_pair do |key, xtypes|
+        old[:xtypes][key] = (old[:xtypes][key] || []) + xtypes
+      end
       old[:doc] = old[:doc].length > 0 ? old[:doc] : new[:doc]
       # Additionally the doc-comment can contain configs and constructor
       old[:members][:cfg] += new[:members][:cfg]
@@ -162,6 +166,14 @@ module JsDuck
       end
     end
 
+    # Creates accessor method for configs marked with @accessor
+    def create_accessors
+      accessors = Accessors.new
+      @classes.each_value do |cls|
+        accessors.create(cls)
+      end
+    end
+
     # Are we dealing with ExtJS 4?
     # True if any of the classes is defined with Ext.define()
     def ext4?

data/lib/jsduck/app.rb

@@ -82,8 +82,6 @@ module JsDuck
         @timer.time(:generating) { puts JsonDuck.generate(@relations.classes) }
       elsif @opts.export == :json
         FileUtils.mkdir(@opts.output_dir)
-        init_output_dirs
-        @timer.time(:generating) { write_src(parsed_files) }
         @timer.time(:generating) { format_classes }
         @timer.time(:generating) { write_classes }
       else
@@ -114,7 +112,7 @@ module JsDuck
     def parallel_parse(filenames)
       @parallel.map(filenames) do |fname|
         Logger.instance.log("Parsing #{fname} ...")
-        SourceFile.new(IO.read(fname), fname)
+        SourceFile.new(IO.read(fname), fname, @opts)
       end
     end
 
@@ -127,6 +125,7 @@ module JsDuck
       end
       agr.classify_orphans
       agr.create_global_class unless @opts.ignore_global
+      agr.create_accessors
       agr.append_ext4_event_options
       agr.result
     end
@@ -179,9 +178,10 @@ module JsDuck
     # Writes JSON export or JsonP file for each class
     def write_classes
       exporter = Exporter.new(@relations)
-      renderer = Renderer.new
+      renderer = Renderer.new(@opts)
+      dir = @opts.output_dir + (@opts.export ? "" : "/output")
       @parallel.each(@relations.classes) do |cls|
-        filename = @opts.output_dir+"/output/" + cls[:name] + (@opts.export ? ".json" : ".js")
+        filename = dir + "/" + cls[:name] + (@opts.export ? ".json" : ".js")
         Logger.instance.log("Writing to #{filename} ...")
         data = exporter.export(cls)
         if @opts.export
@@ -251,6 +251,7 @@ module JsDuck
         "{footer}" => "<div id='footer-content' style='display: none'>#{@opts.footer}</div>",
         "{extjs_path}" => @opts.extjs_path,
         "{local_storage_db}" => @opts.local_storage_db,
+        "{show_print_button}" => @opts.seo ? "true" : "false",
         "{welcome}" => @welcome.to_html,
         "{categories}" => @categories.to_html,
         "{guides}" => @guides.to_html,

data/lib/jsduck/class_formatter.rb

@@ -39,21 +39,25 @@ module JsDuck
       if expandable?(m) || @formatter.too_long?(m[:doc])
         m[:shortDoc] = @formatter.shorten(m[:doc])
       end
-      m[:html_type] = format_type(m[:type]) if m[:type] && @include_types
-      m[:params] = m[:params].map {|p| format_item(p) } if m[:params]
-      m[:return] = format_item(m[:return]) if m[:return]
-      m[:properties] = m[:properties].map {|b| format_item(b) } if m[:properties]
+
+      # We don't validate and format CSS var and mixin type definitions
+      is_css_tag = m[:tagname] == :css_var || m[:tagname] == :css_mixin
+
+      m[:html_type] = (@include_types && !is_css_tag) ? format_type(m[:type]) : m[:type] if m[:type]
+      m[:params] = m[:params].map {|p| format_item(p, is_css_tag) } if m[:params]
+      m[:return] = format_item(m[:return], is_css_tag) if m[:return]
+      m[:properties] = m[:properties].map {|b| format_item(b, is_css_tag) } if m[:properties]
       m
     end
 
     def expandable?(m)
-      m[:params] || (m[:properties] && m[:properties].length > 0) || m[:default] || m[:deprecated]
+      m[:params] || (m[:properties] && m[:properties].length > 0) || m[:default] || m[:deprecated] || m[:template]
     end
 
-    def format_item(it)
+    def format_item(it, is_css_tag)
       it[:doc] = @formatter.format(it[:doc]) if it[:doc]
-      it[:html_type] = format_type(it[:type]) if it[:type] && @include_types
-      it[:properties] = it[:properties].map {|s| format_item(s) } if it[:properties]
+      it[:html_type] = (@include_types && !is_css_tag) ? format_type(it[:type]) : it[:type] if it[:type]
+      it[:properties] = it[:properties].map {|s| format_item(s, is_css_tag) } if it[:properties]
       it
     end
 

data/lib/jsduck/css_parser.rb

@@ -4,9 +4,9 @@ require 'jsduck/doc_parser'
 module JsDuck
 
   class CssParser
-    def initialize(input)
+    def initialize(input, options = {})
       @lex = Lexer.new(input)
-      @doc_parser = DocParser.new(:css)
+      @doc_parser = DocParser.new(:css, options[:meta_tags])
       @docs = []
     end
 

data/lib/jsduck/doc_formatter.rb

@@ -202,14 +202,14 @@ module JsDuck
       # Use the canonical class name for link (not some alternateClassName)
       cls = @relations[cls].full_name
       # prepend type name to member name
-      member = member && (get_member(cls, member, type)[:tagname].to_s + "-" + member)
+      member = member && get_member(cls, member, type)
 
       @link_tpl.gsub(/(%[\w#-])/) do
         case $1
         when '%c'
           cls
         when '%m'
-          member ? member : ""
+          member ? member[:id] : ""
         when '%#'
           member ? "#" : ""
         when '%-'

data/lib/jsduck/doc_parser.rb

@@ -24,9 +24,14 @@ module JsDuck
   #
   class DocParser
     # Pass in :css to be able to parse CSS doc-comments
-    def initialize(mode = :js)
+    def initialize(mode = :js, meta_tags = nil)
       @ident_pattern = (mode == :css) ? /\$?[\w-]+/ : /[$\w]\w*/
       @ident_chain_pattern = (mode == :css) ? /\$?[\w-]+(\.[\w-]+)*/ : /[$\w]\w*(\.\w+)*/
+
+      @meta_tags_map = {}
+      (meta_tags || []).each do |tag|
+        @meta_tags_map[tag[:name]] = true
+      end
     end
 
     def parse(input)
@@ -54,12 +59,23 @@ module JsDuck
       # Now we are left with only two types of lines:
       # - those beginning with *
       # - and those without it
+      indent = nil
       input.each_line do |line|
         line.chomp!
         if line =~ /\A\s*\*\s?(.*)\Z/
+          # When comment contains *-lines, switch indent-trimming off
+          indent = 0
           result << $1
-        else
+        elsif line =~ /\A\s*\Z/
+          # pass-through empty lines
           result << line
+        elsif indent == nil && line =~ /\A(\s*)(.*?\Z)/
+          # When indent not measured, measure it and remember
+          indent = $1.length
+          result << $2
+        else
+          # Trim away indent if available
+          result << line.sub(/\A\s{0,#{indent||0}}/, "")
         end
       end
       return result.join("\n")
@@ -106,10 +122,6 @@ module JsDuck
           at_member
         elsif look(/@alias\b/)
           at_alias
-        elsif look(/@author\b/)
-          at_author
-        elsif look(/@docauthor\b/)
-          at_docauthor
         elsif look(/@deprecated\b/)
           at_deprecated
         elsif look(/@var\b/)
@@ -122,6 +134,10 @@ module JsDuck
           boolean_at_tag(/@(private|ignore|hide)/, :private)
         elsif look(/@protected\b/)
           boolean_at_tag(/@protected/, :protected)
+        elsif look(/@accessor\b/)
+          boolean_at_tag(/@accessor/, :accessor)
+        elsif look(/@template\b/)
+          boolean_at_tag(/@template/, :template)
         elsif look(/@markdown\b/)
           # this is detected just to be ignored
           boolean_at_tag(/@markdown/, :markdown)
@@ -129,7 +145,16 @@ module JsDuck
           # this is detected just to be ignored
           boolean_at_tag(/@abstract/, :abstract)
         elsif look(/@/)
-          @current_tag[:doc] += @input.scan(/@/)
+          @input.scan(/@/)
+          if @meta_tags_map[look(/\w+/)]
+            add_tag(:meta)
+            @current_tag[:name] = match(/\w+/)
+            skip_horiz_white
+            @current_tag[:content] = @input.scan(/.*$/)
+            skip_white
+          else
+            @current_tag[:doc] += "@"
+          end
         elsif look(/[^@]/)
           @current_tag[:doc] += @input.scan(/[^@]+/)
         end
@@ -303,24 +328,6 @@ module JsDuck
       skip_white
     end
 
-    # matches @author some name ... newline
-    def at_author
-      match(/@author/)
-      add_tag(:author)
-      skip_horiz_white
-      @current_tag[:name] = @input.scan(/.*$/)
-      skip_white
-    end
-
-    # matches @docauthor some name ... newline
-    def at_docauthor
-      match(/@docauthor/)
-      add_tag(:docauthor)
-      skip_horiz_white
-      @current_tag[:name] = @input.scan(/.*$/)
-      skip_white
-    end
-
     # matches @deprecated <version> some text ... newline
     def at_deprecated
       match(/@deprecated/)

data/lib/jsduck/exporter.rb

@@ -42,7 +42,7 @@ module JsDuck
 
     def compact_member(m)
       m_copy = {}
-      [:name, :tagname, :owner, :protected, :static, :deprecated, :required].each do |key|
+      [:name, :tagname, :owner, :protected, :static, :deprecated, :required, :template, :id].each do |key|
         m_copy[key] = m[key]
       end
       m_copy

data/lib/jsduck/guides.rb

@@ -29,9 +29,18 @@ module JsDuck
     end
 
     def write_guide(guide, dir)
-      in_dir = @path + "/" + guide["name"]
+      guide_dir = @path + "/guides/" + guide["name"]
+      tutorial_dir = @path + "/tutorials/" + guide["name"]
       out_dir = dir + "/" + guide["name"]
-      return Logger.instance.warn("Guide #{in_dir} not found") unless File.exists?(in_dir)
+
+      if File.exists?(guide_dir)
+        in_dir = guide_dir
+      elsif File.exists?(tutorial_dir)
+        in_dir = tutorial_dir
+      else
+        return Logger.instance.warn("Guide #{guide_dir} / #{tutorial_dir} not found")
+      end
+
       guide_file = in_dir + "/README.md"
       return Logger.instance.warn("README.md not found in #{in_dir}") unless File.exists?(guide_file)
 

data/lib/jsduck/js_parser.rb

@@ -6,10 +6,11 @@ require 'jsduck/js_literal_builder'
 module JsDuck
 
   class JsParser < JsLiteralParser
-    def initialize(input)
+    def initialize(input, options = {})
       super(input)
-      @doc_parser = DocParser.new
+      @doc_parser = DocParser.new(:js, options[:meta_tags])
       @docs = []
+      @ext_namespaces = options[:ext_namespaces] || ["Ext"]
     end
 
     # Parses the whole JavaScript block and returns array where for
@@ -76,9 +77,9 @@ module JsDuck
         function
       elsif look("var")
         var_declaration
-      elsif look("Ext", ".", "define", "(", :string)
+      elsif ext_look(:ns, ".", "define", "(", :string)
         ext_define
-      elsif look("Ext", ".", "ClassManager", ".", "create", "(", :string)
+      elsif ext_look(:ns, ".", "ClassManager", ".", "create", "(", :string)
         ext_define
       elsif look(:ident, ":") || look(:string, ":")
         property_literal
@@ -155,12 +156,14 @@ module JsDuck
       return chain
     end
 
-    # <expression> := <function> | <ext-extend> | <literal>
+    # <expression> := <function> | <ext-extend> | <ext-base-css-prefix> | <literal>
     def expression
       if look("function")
         function
-      elsif look("Ext", ".", "extend")
+      elsif ext_look(:ns, ".", "extend")
         ext_extend
+      elsif ext_look(:ns, ".", "baseCSSPrefix", "+", :string)
+        ext_base_css_prefix
       else
         my_literal
       end
@@ -194,16 +197,26 @@ module JsDuck
 
     # <ext-extend> := "Ext" "." "extend" "(" <ident-chain> "," ...
     def ext_extend
-      match("Ext", ".", "extend", "(")
+      match(:ident, ".", "extend", "(")
       return {
         :type => :ext_extend,
         :extend => ident_chain,
       }
     end
 
+    # <ext-base-css-prefix> := "Ext" "." "baseCSSPrefix" "+" <string>
+    def ext_base_css_prefix
+      match(:ident, ".", "baseCSSPrefix", "+")
+      return {
+        :type => :literal,
+        :class => "String",
+        :value => '"x-' + match(:string)[:value] + '"',
+      }
+    end
+
     # <ext-define> := "Ext" "." ["define" | "ClassManager" "." "create" ] "(" <string> "," <ext-define-cfg>
     def ext_define
-      match("Ext", ".");
+      match(:ident, ".");
       look("define") ? match("define") : match("ClassManager", ".", "create");
       name = match("(", :string)[:value]
 
@@ -338,6 +351,15 @@ module JsDuck
       }
     end
 
+    # Like look() but tries to match as the first argument all the
+    # names listed in @ext_namespaces
+    def ext_look(placeholder, *args)
+      @ext_namespaces.each do |ns|
+        return true if look(ns, *args)
+      end
+      return false
+    end
+
   end
 
 end