jsduck 4.0.beta → 4.0.beta2

data/lib/jsduck/inherit_doc.rb

@@ -16,7 +16,7 @@ module JsDuck
 
         new_cfgs = []
         cls.all_local_members.each do |member|
-          if member[:inheritdoc] || member[:autodetected]
+          if member[:inheritdoc]
             resolve(member, new_cfgs)
           end
         end
@@ -35,6 +35,10 @@ module JsDuck
         m[:params] = parent[:params] if parent[:params]
         m[:return] = parent[:return] if parent[:return]
 
+        if m[:autodetected]
+          m[:meta] = parent[:meta].merge(m[:meta])
+        end
+
         # remember properties that have changed to configs
         if m[:tagname] != parent[:tagname]
           new_cfgs << m
@@ -113,6 +117,7 @@ module JsDuck
         end
       end
 
+      #pp parent[:doc]
       return parent[:inheritdoc] ? find_parent(parent) : parent
     end
 
@@ -122,22 +127,28 @@ module JsDuck
       tagname = inherit[:type] || m[:tagname]
       static = inherit[:static] || m[:meta][:static]
 
-      # Auto-detected properties can override either a property or a
-      # config. So look for both types.
-      if m[:autodetected] && tagname == :property
-        cfg = cls.get_members(name, :cfg, static)[0]
-        prop = cls.get_members(name, :property, static)[0]
-
-        if cfg && prop
-          prop
-        elsif cfg
-          cfg
-        elsif prop
-          prop
+      if m[:autodetected]
+        # Auto-detected properties can override either a property or a
+        # config. So look for both types.
+        if tagname == :property
+          cfg = cls.get_members(name, :cfg, static || false)[0]
+          prop = cls.get_members(name, :property, static || false)[0]
+
+          if cfg && prop
+            prop
+          elsif cfg
+            cfg
+          elsif prop
+            prop
+          else
+            nil
+          end
+
         else
-          nil
+          # Unless the auto-detected member is detected as static,
+          # look only at instance members.
+          cls.get_members(name, tagname, static || false)[0]
         end
-
       else
         cls.get_members(name, tagname, static)[0]
       end

data/lib/jsduck/lint.rb

@@ -17,6 +17,7 @@ module JsDuck
       warn_optional_params
       warn_duplicate_params
       warn_duplicate_members
+      warn_empty_enums
     end
 
     # print warning for each member or parameter with no name
@@ -94,6 +95,15 @@ module JsDuck
       end
     end
 
+    # print warnings for enums with no values
+    def warn_empty_enums
+      @relations.each do |cls|
+        if cls[:enum] && cls[:members][:property].length == 0
+          warn(:enum, "Enum #{cls[:name]} defined without values in it", cls)
+        end
+      end
+    end
+
     # Loops through all members of all classes
     def each_member(&block)
       @relations.each {|cls| cls.all_local_members.each(&block) }

data/lib/jsduck/logger.rb

@@ -31,6 +31,7 @@ module JsDuck
         [:sing_static, "Singleton class member marked as @static"],
         [:type_syntax, "Syntax error in {type definition}"],
         [:type_name, "Unknown type referenced in {type definition}"],
+        [:enum, "Enum defined without any values in it"],
 
         [:image, "{@img} referring to missing file"],
         [:image_unused, "An image exists in --images dir that's not used"],
@@ -101,6 +102,8 @@ module JsDuck
       elsif !@warnings.has_key?(type)
         warn(nil, "Unknown warning type #{type}")
       end
+
+      return false
     end
 
     # Formats filename and line number for output

data/lib/jsduck/markdown.rb

@@ -0,0 +1,46 @@
+
+module JsDuck
+
+  # Wrapper which chooses the available Markdown implementation and
+  # provides a uniform interface to it.
+  #
+  # Possible engines in order of preference:
+  #
+  # - rdiscount
+  # - kramdown
+  #
+  class Markdown
+
+    if RUBY_PLATFORM == "java"
+      require "kramdown"
+      begin
+        @@engine = :kramdown
+      rescue LoadError
+        throw "ERROR: Kramdown gem not available."
+      end
+    else
+      begin
+        require "rdiscount"
+        @@engine = :rdiscount
+      rescue LoadError
+        begin
+          require "kramdown"
+          @@engine = :kramdown
+        rescue LoadError
+          throw "ERROR: Neither RDiscount nor Kramdown gem available."
+        end
+      end
+    end
+
+    # Converts Markdown text into HTML
+    def self.to_html(input)
+      if @@engine == :rdiscount
+        RDiscount.new(input).to_html
+      else
+        Kramdown::Document.new(input).to_html
+      end
+    end
+
+  end
+
+end

data/lib/jsduck/merger.rb

@@ -44,8 +44,10 @@ module JsDuck
       h[:extends] = nil if h[:extends] == "Object"
 
       h[:aliases] = build_aliases_hash(h[:aliases] || [])
+
       # Used by Aggregator to determine if we're dealing with Ext4 code
-      h[:code_type] = code[:tagname]
+      h[:code_type] = code[:code_type] if code[:code_type]
+
       h[:members] = Class.default_members_hash
       h[:statics] = Class.default_members_hash
 

data/lib/jsduck/options.rb

@@ -44,6 +44,7 @@ module JsDuck
     attr_accessor :local_storage_db
     attr_accessor :touch_examples_ui
     attr_accessor :ext_namespaces
+    attr_accessor :imports
 
     def initialize
       @input_files = []
@@ -75,11 +76,11 @@ module JsDuck
       ]
       @meta_tag_paths = []
 
-      @version = "4.0.beta"
+      @version = "4.0.beta2"
 
       # Customizing output
-      @title = "Sencha Docs - Ext JS"
-      @header = "<strong>Sencha Docs</strong> Ext JS"
+      @title = "Ext JS - Sencha Docs"
+      @header = "<strong>Ext JS</strong> Sencha Docs"
       @footer = "Generated with <a href='https://github.com/senchalabs/jsduck'>JSDuck</a> #{@version}."
       @head_html = ""
       @body_html = ""
@@ -112,6 +113,7 @@ module JsDuck
       @local_storage_db = "docs"
       @touch_examples_ui = false
       @ext_namespaces = ["Ext"]
+      @imports = []
 
       # enable all warnings except :link_auto
       Logger.instance.set_warning(:all, true)
@@ -181,7 +183,7 @@ module JsDuck
 
         opts.on('--title=TEXT',
           "Custom title text for the documentation.",
-          "Defaults to 'Sencha Docs - Ext JS'", " ") do |text|
+          "Defaults to 'Ext JS - Sencha Docs'", " ") do |text|
           @title = text
           @header = text.sub(/^(.*?) +- +/, "<strong>\\1 </strong>")
         end
@@ -360,6 +362,17 @@ module JsDuck
           @ext_namespaces = ns
         end
 
+        opts.on('--import=VERSION:PATH',
+          "Imports docs of a particular version generating @since tags.",
+          "Several versions can be imported using the option multiple times.",
+          "To specify the current version, leave the :PATH portion off.", " ") do |v|
+          if v =~ /\A(.*?):(.*)\Z/
+            @imports << {:version => $1, :path => canonical($2)}
+          else
+            @imports << {:version => v}
+          end
+        end
+
         opts.on('--config=PATH',
           "Loads config options from JSON file.", " ") do |path|
           path = canonical(path)

data/lib/jsduck/parallel_wrap.rb

@@ -5,25 +5,26 @@ module JsDuck
   # Wrapper around the parallel gem that falls back to simple
   # Array#map and Array#each when :in_processes => 0 specified.
   class ParallelWrap
+    @@in_processes = nil
 
-    # Takes config object for parallel
-    def initialize(cfg = {})
-      @cfg = cfg
+    # Sets globally the nr of processes to use.
+    def self.in_processes=(n)
+      @@in_processes = n
     end
 
-    def each(arr, &block)
-      if @cfg[:in_processes] == 0
+    def self.each(arr, &block)
+      if @@in_processes == 0
         arr.each &block
       else
-        Parallel.each(arr, @cfg, &block)
+        Parallel.each(arr, {:in_processes => @@in_processes}, &block)
       end
     end
 
-    def map(arr, &block)
-      if @cfg[:in_processes] == 0
+    def self.map(arr, &block)
+      if @@in_processes == 0
         arr.map &block
       else
-        Parallel.map(arr, @cfg, &block)
+        Parallel.map(arr, {:in_processes => @@in_processes}, &block)
       end
     end
   end

data/lib/jsduck/renderer.rb

@@ -20,6 +20,7 @@ module JsDuck
               render_meta_data(@cls[:html_meta], :top),
               render_private_class_notice,
               @cls[:doc],
+              render_enum_class_notice,
               render_meta_data(@cls[:html_meta], :bottom),
             "</div>",
             "<div class='members'>",
@@ -38,6 +39,26 @@ module JsDuck
       ]
     end
 
+    def render_enum_class_notice
+      return if !@cls[:enum]
+
+      if @cls[:enum][:type] == "String"
+        first = @cls[:members][:property][0] || {:name => 'foo', :default => '"foo"'}
+        [
+          "<p class='enum'><strong>ENUM:</strong> ",
+          "This enumeration defines a set of String values. ",
+          "It exists primarily for documentation purposes - ",
+          "in code use the actual string values like #{first[:default]}, ",
+          "don't reference them through this class like #{@cls[:name]}.#{first[:name]}.</p>",
+        ]
+      else
+        [
+          "<p class='enum'><strong>ENUM:</strong> ",
+          "This enumeration defines a set of #{@cls[:enum][:type]} values.</p>",
+        ]
+      end
+    end
+
     def render_meta_data(meta_data, position)
       return if meta_data.size == 0
 

data/lib/jsduck/source_file.rb

@@ -19,7 +19,7 @@ module JsDuck
       @html_filename = ""
       @links = {}
 
-      @docs = SourceFileParser.instance.parse(@contents, @filename, options)
+      @docs = SourceFileParser.new.parse(@contents, @filename, options)
 
       @docs.map do |docset|
         link(docset[:linenr], docset)

data/lib/jsduck/source_file_parser.rb

@@ -1,4 +1,3 @@
-require 'singleton'
 require 'jsduck/js_parser'
 require 'jsduck/css_parser'
 require 'jsduck/doc_parser'
@@ -15,7 +14,6 @@ module JsDuck
   # This is the class that brings together all the different steps of
   # parsing the source.
   class SourceFileParser
-    include Singleton
 
     def initialize
       @doc_type = DocType.new

data/lib/jsduck/source_writer.rb

@@ -1,13 +1,13 @@
 require 'jsduck/logger'
+require 'jsduck/parallel_wrap'
 require 'fileutils'
 
 module JsDuck
 
   # Writes HTML JavaScript/CSS source into HTML files.
   class SourceWriter
-    def initialize(source_files, parallel)
+    def initialize(source_files)
       @source_files = source_files
-      @parallel = parallel
     end
 
     # Writes all source files as HTML files into destination dir.
@@ -15,7 +15,7 @@ module JsDuck
       generate_html_filenames
 
       FileUtils.mkdir(destination)
-      @parallel.each(@source_files) do |file|
+      ParallelWrap.each(@source_files) do |file|
         Logger.instance.log("Writing source", file.html_filename)
         write_single(destination + "/" + file.html_filename, file.to_html)
       end

data/lib/jsduck/tag/new.rb

@@ -0,0 +1,20 @@
+require "jsduck/meta_tag"
+require "jsduck/logger"
+
+module JsDuck::Tag
+  # Implementation of @new tag.
+  class New < JsDuck::MetaTag
+    def initialize
+      @name = "new"
+      @key = :new
+      @signature = {:long => "&#9733;", :short => "&#9733;"} # unicode black star char
+      @boolean = true
+    end
+
+    def to_value(contents)
+      true
+    end
+
+  end
+end
+

data/lib/jsduck/tag/since.rb

@@ -0,0 +1,26 @@
+require "jsduck/meta_tag"
+require "jsduck/logger"
+
+module JsDuck::Tag
+  # Implementation of @since tag.
+  class Since < JsDuck::MetaTag
+    def initialize
+      @name = "since"
+      @key = :since
+    end
+
+    def to_value(contents)
+      if contents.length > 1
+        JsDuck::Logger.instance.warn(nil, "Only one @since tag allowed per class/member.")
+      end
+      contents[0]
+    end
+
+    def to_html(version)
+      <<-EOHTML
+        <p>Available since: <b>#{version}</b></p>
+      EOHTML
+    end
+  end
+end
+

data/lib/jsduck/type_parser.rb

@@ -8,6 +8,8 @@ module JsDuck
   #
   # 1. Traditional type expressions found in ExtJS code:
   #
+  #     "string"
+  #     3.14
   #     SomeType
   #     Name.spaced.Type
   #     Number[]
@@ -141,7 +143,7 @@ module JsDuck
     #
     #     <array-type> ::= <atomic-type> [ "[]" ]*
     #
-    #     <atomic-type> ::= <union-type> | <record-type> | <function-type> | <type-name>
+    #     <atomic-type> ::= <union-type> | <record-type> | <function-type> | <string-literal> | <type-name>
     #
     def null_type
       if nullability = @input.scan(/[?!]/)
@@ -154,6 +156,10 @@ module JsDuck
         return false unless record_type
       elsif @input.check(/function\(/)
         return false unless function_type
+      elsif @input.check(/['"]/)
+        return false unless string_literal
+      elsif @input.check(/\d/)
+        return false unless number_literal
       else
         return false unless type_name
       end
@@ -289,6 +295,24 @@ module JsDuck
       true
     end
 
+    #
+    #     <string-literal> ::= '.*' | ".*"
+    #
+    def string_literal
+      @out << @input.scan(/"([^\\"]|\\.)*?"|'([^\\']|\\.)*?'/)
+
+      true
+    end
+
+    #
+    #     <number-literal> ::= <digit>+ [ "." <digit>+ ]
+    #
+    def number_literal
+      @out << @input.scan(/\d+(\.\d+)?/)
+
+      true
+    end
+
     #
     #     <type-name> ::= <type-application> | "*"
     #