jsduck 3.0.1 → 3.1.0

data/lib/jsduck/examples.rb

@@ -1,22 +1,26 @@
 require 'jsduck/json_duck'
+require 'jsduck/null_object'
 
 module JsDuck
 
   # Reads in examples JSON file
   class Examples
-    def initialize
-      @examples = []
+    # Creates Examples object from filename.
+    def self.create(filename)
+      if filename
+        Examples.new(filename)
+      else
+        NullObject.new(:to_array => [])
+      end
     end
 
     # Parses examples config file
-    def parse(filename)
+    def initialize(filename)
       @examples = JsonDuck.read(filename)
     end
 
     # Writes examples JSON file to dir
     def write(dir)
-      return if @examples.length == 0
-
       FileUtils.mkdir(dir) unless File.exists?(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.

data/lib/jsduck/file_categories.rb

@@ -0,0 +1,65 @@
+module JsDuck
+
+  # Reads categories info from config file
+  class FileCategories
+    def initialize(filename, relations)
+      @filename = filename
+      @relations = relations
+    end
+
+    # Parses categories in JSON file
+    def generate
+      @categories = JsonDuck.read(@filename)
+
+      # Don't crash if old syntax is used.
+      if @categories.is_a?(Hash) && @categories["categories"]
+        Logger.instance.warn(:old_cat_format, 'Update categories file to contain just the array inside {"categories": [...]}')
+        @categories = @categories["categories"]
+      end
+
+      # Perform expansion on all class names containing * wildcard
+      @categories.each do |cat|
+        cat["groups"].each do |group|
+          group["classes"] = group["classes"].map do |name|
+            expand(name) # name =~ /\*/ ? expand(name) : name
+          end.flatten
+        end
+      end
+
+      validate
+
+      @categories
+    end
+
+    # Expands class name like 'Foo.*' into multiple class names.
+    def expand(name)
+      re = Regexp.new("^" + name.split(/\*/, -1).map {|part| Regexp.escape(part) }.join('.*') + "$")
+      classes = @relations.to_a.find_all {|cls| re =~ cls[:name] && !cls[:private] }.map {|cls| cls[:name] }.sort
+      if classes.length == 0
+        Logger.instance.warn(:cat_no_match, "No class found matching a pattern '#{name}' in categories file.")
+      end
+      classes
+    end
+
+    # Prints warnings for missing classes in categories file
+    def validate
+      # Build a map of all classes listed in categories
+      listed_classes = {}
+      @categories.each do |cat|
+        cat["groups"].each do |group|
+          group["classes"].each do |cls_name|
+            listed_classes[cls_name] = true
+          end
+        end
+      end
+
+      # Check that each existing non-private class is listed
+      @relations.each do |cls|
+        unless listed_classes[cls[:name]] || cls[:private]
+          Logger.instance.warn(:cat_class_missing, "Class '#{cls[:name]}' not found in categories file")
+        end
+      end
+    end
+  end
+
+end

data/lib/jsduck/full_exporter.rb

@@ -0,0 +1,29 @@
+require 'jsduck/class'
+
+module JsDuck
+
+  # Exporter for all the class docs.
+  class FullExporter
+    def initialize(relations, opts)
+      @relations = relations
+    end
+
+    # Returns all data in Class object as hash.
+    def export(cls)
+      h = cls.to_hash
+      h[:members] = {}
+      Class.default_members_hash.each_key do |key|
+        h[:members][key] = cls.members(key)
+        h[:statics][key] = cls.members(key, :statics)
+      end
+      h[:component] = cls.inherits_from?("Ext.Component")
+      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
+    end
+
+  end
+
+end

data/lib/jsduck/guides.rb

@@ -1,26 +1,30 @@
 require 'jsduck/logger'
 require 'jsduck/json_duck'
+require 'jsduck/null_object'
 require 'fileutils'
 
 module JsDuck
 
   # Reads in guides and converts them to JsonP files
   class Guides
-    def initialize(formatter)
-      @formatter = formatter
-      @guides = []
+    # 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 => "")
+      end
     end
 
     # Parses guides config file
-    def parse(filename)
+    def initialize(filename, formatter)
       @path = File.dirname(filename)
       @guides = JsonDuck.read(filename)
+      @formatter = formatter
     end
 
     # Writes all guides to given dir in JsonP format
     def write(dir)
-      return if @guides.length == 0
-
       FileUtils.mkdir(dir) unless File.exists?(dir)
       @guides.each {|group| group["items"].each {|g| write_guide(g, dir) } }
       # Write the JSON to output dir, so it's available in released
@@ -38,11 +42,11 @@ module JsDuck
       elsif File.exists?(tutorial_dir)
         in_dir = tutorial_dir
       else
-        return Logger.instance.warn("Guide #{guide_dir} / #{tutorial_dir} not found")
+        return Logger.instance.warn(:guide, "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)
+      return Logger.instance.warn(:guide, "README.md not found in #{in_dir}") unless File.exists?(guide_file)
 
       Logger.instance.log("Writing guide", out_dir)
       # Copy the whole guide dir over
@@ -63,8 +67,6 @@ module JsDuck
 
     # Returns HTML listing of guides
     def to_html
-      return "" if @guides.length == 0
-
       html = @guides.map do |group|
         [
           "<h3>#{group['title']}</h3>",

data/lib/jsduck/images.rb

@@ -35,7 +35,7 @@ module JsDuck
     def copy(output_dir)
       @images.each_key do |img|
         unless copy_img(img, output_dir)
-          Logger.instance.warn("Image not found.", img)
+          Logger.instance.warn(:image, "Image not found.", img)
         end
       end
       report_unused
@@ -62,7 +62,7 @@ module JsDuck
     def report_unused
       @paths.each_pair do |path, map|
         map.each_pair do |img, used|
-          Logger.instance.warn("Image not used.", img) unless used
+          Logger.instance.warn(:image_unused, "Image not used.", img) unless used
         end
       end
     end

data/lib/jsduck/index_html.rb

@@ -0,0 +1,67 @@
+require 'jsduck/logger'
+require 'fileutils'
+
+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)
+      @opts = opts
+    end
+
+    # In normal mode creates index.html.
+    #
+    # When --seo enabled, creates index.php, template.html and print-template.html.
+    def write
+      if @opts.seo
+        FileUtils.cp(@opts.template_dir+"/index.php", @opts.output_dir+"/index.php")
+        create_template_html(@opts.template_dir+"/template.html", @opts.output_dir+"/template.html")
+        create_print_template_html(@opts.template_dir+"/print-template.html", @opts.output_dir+"/print-template.html")
+      else
+        create_template_html(@opts.template_dir+"/template.html", @opts.output_dir+"/index.html")
+      end
+    end
+
+    private
+
+    def create_template_html(in_file, out_file)
+      write_template(in_file, out_file, {
+        "{title}" => @opts.title,
+        "{header}" => @opts.header,
+        "{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",
+        "{touch_examples_ui}" => @opts.touch_examples_ui ? "true" : "false",
+        "{welcome}" => @welcome.to_html,
+        "{categories}" => @categories.to_html,
+        "{guides}" => @guides.to_html,
+        "{head_html}" => @opts.head_html,
+        "{body_html}" => @opts.body_html,
+      })
+    end
+
+    def create_print_template_html(in_file, out_file)
+      write_template(in_file, out_file, {
+        "{title}" => @opts.title,
+        "{header}" => @opts.header,
+      })
+    end
+
+    # Opens in_file, replaces {keys} inside it, writes to out_file
+    def write_template(in_file, out_file, replacements)
+      Logger.instance.log("Writing", out_file)
+      html = IO.read(in_file)
+      html.gsub!(/\{\w+\}/) do |key|
+        replacements[key] ? replacements[key] : key
+      end
+      File.open(out_file, 'w') {|f| f.write(html) }
+    end
+
+  end
+
+end

data/lib/jsduck/inherit_doc.rb

@@ -0,0 +1,75 @@
+require 'jsduck/logger'
+
+module JsDuck
+
+  # Deals with inheriting documentation
+  class InheritDoc
+    def initialize(relations)
+      @relations = relations
+    end
+
+    # Performs all inheriting
+    def resolve_all
+      @relations.each do |cls|
+        cls.all_local_members.each do |member|
+          if member[:inheritdoc]
+            resolve(member)
+          end
+        end
+      end
+    end
+
+    # Copy over doc/params/return from parent member.
+    def resolve(m)
+      parent = find_parent(m)
+      m[:doc] = (m[:doc] + "\n\n" + parent[:doc]).strip
+      m[:params] = parent[:params] if parent[:params]
+      m[:return] = parent[:return] if parent[:return]
+    end
+
+    # Finds parent member of the given member.  When @inheritdoc names
+    # a member to inherit from, finds that member instead.
+    #
+    # If the parent also has @inheritdoc, continues recursively.
+    def find_parent(m)
+      context = m[:files][0]
+      inherit = m[:inheritdoc]
+
+      if inherit[:cls]
+        parent_cls = @relations[inherit[:cls]]
+        unless parent_cls
+          warn("@inheritdoc #{inherit[:cls]}##{inherit[:member]} - class not found", context)
+          return m
+        end
+        parent = parent_cls.get_member(inherit[:member], inherit[:type] || m[:tagname])
+        unless parent
+          warn("@inheritdoc #{inherit[:cls]}##{inherit[:member]} - member not found", context)
+          return m
+        end
+      else
+        parent_cls = @relations[m[:owner]].parent
+        unless parent_cls
+          warn("@inheritdoc - parent class not found", context)
+          return m
+        end
+        parent = parent_cls.get_member(m[:name], m[:tagname])
+        unless parent
+          warn("@inheritdoc - parent member not found", context)
+          return m
+        end
+      end
+
+      if parent[:inheritdoc]
+        find_parent(parent)
+      else
+        parent
+      end
+    end
+
+    def warn(msg, context)
+      Logger.instance.warn(:inheritdoc, msg, context[:filename], context[:linenr])
+    end
+
+  end
+
+end

data/lib/jsduck/js_parser.rb

@@ -172,7 +172,7 @@ module JsDuck
     # <literal> := ...see JsLiteralParser...
     def my_literal
       lit = literal
-      return unless lit
+      return unless lit && literal_expression_end?
 
       cls_map = {
         :string => "String",
@@ -195,6 +195,13 @@ module JsDuck
       {:type => :literal, :class => cls, :value => value}
     end
 
+    # True when we're at the end of literal expression.
+    # ",", ";" and "}" are the normal closing symbols, but for
+    # our docs purposes doc-comment and file end work too.
+    def literal_expression_end?
+      look(",") || look(";") || look("}") || look(:doc_comment) || @lex.empty?
+    end
+
     # <ext-extend> := "Ext" "." "extend" "(" <ident-chain> "," ...
     def ext_extend
       match(:ident, ".", "extend", "(")

data/lib/jsduck/lint.rb

@@ -22,8 +22,8 @@ module JsDuck
     def warn_globals
       global = @relations["global"]
       return unless global
-      global.each_member do |member|
-        warn("Global #{member[:tagname]}: #{member[:name]}", member)
+      global.all_local_members.each do |member|
+        warn(:global, "Global #{member[:tagname]}: #{member[:name]}", member)
       end
     end
 
@@ -31,11 +31,11 @@ module JsDuck
     def warn_unnamed
       each_member do |member|
         if !member[:name] || member[:name] == ""
-          warn("Unnamed #{member[:tagname]}", member)
+          warn(:name_missing, "Unnamed #{member[:tagname]}", member)
         end
         (member[:params] || []).each do |p|
           if !p[:name] || p[:name] == ""
-            warn("Unnamed parameter", member)
+            warn(:name_missing, "Unnamed parameter", member)
           end
         end
       end
@@ -48,7 +48,7 @@ module JsDuck
           optional_found = false
           member[:params].each do |p|
             if optional_found && !p[:optional]
-              warn("Optional param can't be followed by regular param #{p[:name]}", member)
+              warn(:req_after_opt, "Optional param followed by regular param #{p[:name]}", member)
             end
             optional_found = optional_found || p[:optional]
           end
@@ -62,7 +62,7 @@ module JsDuck
         params = {}
         (member[:params] || []).each do |p|
           if params[p[:name]]
-            warn("Duplicate parameter name #{p[:name]}", member)
+            warn(:dup_param, "Duplicate parameter name #{p[:name]}", member)
           end
           params[p[:name]] = true
         end
@@ -71,13 +71,13 @@ module JsDuck
 
     # Loops through all members of all classes
     def each_member(&block)
-      @relations.each {|cls| cls.each_member(&block) }
+      @relations.each {|cls| cls.all_local_members.each(&block) }
     end
 
     # Prints warning + filename and linenumber from doc-context
-    def warn(msg, member)
+    def warn(type, msg, member)
       context = member[:files][0]
-      Logger.instance.warn(msg, context[:filename], context[:linenr])
+      Logger.instance.warn(type, msg, context[:filename], context[:linenr])
     end
 
   end

data/lib/jsduck/logger.rb

@@ -7,12 +7,39 @@ module JsDuck
   class Logger
     include Singleton
 
+    # Set to true to enable verbose logging
     attr_accessor :verbose
-    attr_accessor :warnings
 
     def initialize
       @verbose = false
-      @warnings = true
+      @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"],
+        [:link, "{@link} to unknown class or member"],
+
+        [:alt_name, "Name used as both classname and alternate classname"],
+        [:name_missing, "Member or parameter has no name"],
+        [:dup_param, "Method has two parameters with same name"],
+        [:req_after_opt, "Required parameter comes after optional"],
+        [:subproperty, "@param foo.bar where foo param doesn't exist"],
+        [:sing_static, "Singleton class member marked as @static"],
+        [:type_syntax, "Syntax error in {type definition}"],
+        [:type_name, "Unknown type referenced in {type definition}"],
+
+        [:image, "{@img} referring to missing file"],
+        [:image_unused, "An image exists in --images dir that's not used"],
+        [:cat_old_format, "Categories file uses old deprecated format"],
+        [: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"],
+      ]
+      # Turn on all warnings by default
+      @warnings = {}
+      @warning_docs.each do |w|
+        @warnings[w[0]] = true
+      end
+
       @shown_warnings = {}
     end
 
@@ -23,19 +50,50 @@ module JsDuck
       end
     end
 
+    # Enabled or disables a particular warning
+    # or all warnings when type == :all
+    def set_warning(type, enabled)
+      if type == :all
+        @warnings.each_key do |key|
+          @warnings[key] = enabled
+        end
+      elsif @warnings.has_key?(type)
+        @warnings[type] = enabled
+      else
+        warn(nil, "Warning of type '#{type} doesn't exist")
+      end
+    end
+
+    # get documentation for all warnings
+    def doc_warnings
+      @warning_docs.map {|w| "+#{w[0]} - #{w[1]}" } + [
+        " ",
+        "+all - to turn on all warnings (default)",
+        " ",
+      ]
+    end
+
     # Prints warning message.
     #
+    # The type must be one of predefined warning types which can be
+    # toggled on/off with command-line options, or it can be nil, in
+    # which case the warning is always shown.
+    #
     # Ignores duplicate warnings - only prints the first one.
     # Works best when --processes=0, but it reduces the amount of
     # warnings greatly also when run multiple processes.
     #
     # Optionally filename and line number will be inserted to message.
-    def warn(msg, filename=nil, line=nil)
+    def warn(type, msg, filename=nil, line=nil)
       msg = "Warning: " + format(filename, line) + " " + msg
 
-      if @warnings && !@shown_warnings[msg]
-        $stderr.puts msg
-        @shown_warnings[msg] = true
+      if type == nil || @warnings[type]
+        if !@shown_warnings[msg]
+          $stderr.puts msg
+          @shown_warnings[msg] = true
+        end
+      elsif !@warnings.has_key?(type)
+        warn(nil, "Unknown warning type #{type}")
       end
     end