jsduck 5.3.4 → 6.0.0beta

data/lib/jsduck/util/json.rb

@@ -17,9 +17,9 @@ module JsDuck
         @pretty = false
       end
 
-      # Set to true to turn on pretty-formatting of JSON
-      def pretty=(pretty)
-        @pretty = pretty
+      # Configures the pretty-formatting from command line options.
+      def configure(opts)
+        @pretty = true if opts.pretty_json
       end
 
       # Turns object into JSON, places it inside JavaScript that calls the

data/lib/jsduck/util/null_object.rb

@@ -15,7 +15,20 @@ module JsDuck
       end
 
       def method_missing(meth, *args, &block)
-        @methods.has_key?(meth) ? @methods[meth] : self
+        if @methods.has_key?(meth)
+          value = @methods[meth]
+          if value.respond_to?(:call)
+            value.call(*args, &block)
+          else
+            value
+          end
+        else
+          self
+        end
+      end
+
+      def respond_to?(meth)
+        @methods.has_key?(meth)
       end
     end
 

data/lib/jsduck/util/parallel.rb

@@ -1,3 +1,4 @@
+require 'jsduck/util/os'
 require 'parallel'
 
 module JsDuck
@@ -8,9 +9,12 @@ module JsDuck
     class Parallel
       @@in_processes = nil
 
-      # Sets globally the nr of processes to use.
-      def self.in_processes=(n)
-        @@in_processes = n
+      # Configures the logger to use as many processes as set in
+      # command line options.  When in Windows, turns the parallel
+      # processing off by default.
+      def self.configure(opts)
+        @@in_processes = 0 if Util::OS::windows?
+        @@in_processes = opts.processes if opts.processes
       end
 
       def self.each(arr, &block)

data/lib/jsduck/version.rb

@@ -1,5 +1,5 @@
 # This file is updated by rake bump task.
 # Do not edit by hand.
 module JsDuck
-  VERSION = "5.3.4"
+  VERSION = "6.0.0beta"
 end

data/lib/jsduck/warning/registry.rb

@@ -1,5 +1,6 @@
 require 'jsduck/warning/basic'
 require 'jsduck/warning/nodoc'
+require 'jsduck/warning/tag'
 require 'jsduck/warning/deprecated'
 require 'jsduck/warning/all'
 require 'jsduck/warning/warn_exception'
@@ -19,7 +20,6 @@ module JsDuck
           [:global, "Member doesn't belong to any class"],
           [:inheritdoc, "@inheritdoc referring to unknown class or member"],
           [:extend, "@extend/mixin/requires/uses referring to unknown class"],
-          [:tag, "Use of unsupported @tag"],
           [:tag_repeated, "An @tag used multiple times, but only once allowed"],
           [:tag_syntax, "@tag syntax error"],
           [:link, "{@link} to unknown class or member"],
@@ -42,7 +42,6 @@ module JsDuck
 
           [: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"],
@@ -53,6 +52,9 @@ module JsDuck
           register(w[0], Warning::Basic.new(w[0], w[1]))
         end
 
+        # :tag warning
+        register(:tag, Warning::Tag.new)
+
         # :nodoc warning
         register(:nodoc, Warning::Nodoc.new)
 

data/lib/jsduck/warning/tag.rb

@@ -0,0 +1,57 @@
+module JsDuck
+  module Warning
+
+    # Unknown tag warning.
+    class Tag
+
+      # Creates the :tag warning type
+      def initialize
+        @rules = []
+        # disable by default
+        set(false)
+      end
+
+      # Enables or disables a particular sub-warning
+      def set(enabled, path_pattern=nil, tagnames=[])
+        @rules.unshift({
+          :enabled => enabled,
+          :tagnames => tagnames,
+          :path_re => path_pattern ? Regexp.new(Regexp.escape(path_pattern)) : nil
+        })
+      end
+
+      # True when the warning is enabled for the given filename and
+      # params combination where params contains one tagname.
+      def enabled?(filename="", params=[])
+        tagname = params[0]
+
+        # Filter out the most recently added rule that applies to our current item
+        match = @rules.find do |r|
+          (r[:tagnames].empty? || r[:tagnames].include?(tagname)) &&
+            (r[:path_re].nil? || r[:path_re] =~ filename)
+        end
+
+        return match[:enabled]
+      end
+
+      # Extensive documentation for :nodoc warning
+      def doc
+        [
+          "",
+          " +tag(<name1>,<name2>,...) - Use of unsupported @tag",
+          "",
+          "     This warning type can optionally take a list of tag names",
+          "     to limit its effect to only these tags.",
+          "",
+          "     So, to disable warnings for JavaDoc tags @file and @overview",
+          "     which aren't supported by JSDuck:",
+          "",
+          "         --warnings='-tag(file,overview)'",
+          "",
+        ]
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/web/class_icons.rb

@@ -0,0 +1,76 @@
+require 'jsduck/tag_registry'
+require 'jsduck/logger'
+require 'fileutils'
+
+module JsDuck
+  module Web
+    class ClassIcons
+      class << self
+        # Returns CSS class name for an icon of class
+        def get(cls)
+          class_icon_providers.each do |tag|
+            if cls[tag.tagname]
+              return "icon-#{tag.tagname}"
+            end
+          end
+
+          return "icon-class"
+        end
+
+        # Generates CSS for class icons
+        def css
+          css = []
+          class_icon_providers.each do |tag|
+            css << <<-EOCSS
+              #center-container h1.icon-#{tag.tagname} .class-source-link {
+                  background: url(class-icons/#{tag.tagname}-large.png) no-repeat 0 -5px; }
+              #treecontainer .x-grid-cell-inner .icon-#{tag.tagname} {
+                  background: url(class-icons/#{tag.tagname}.png) no-repeat; }
+              #search-dropdown .icon-#{tag.tagname} {
+                  background: url(class-icons/#{tag.tagname}.png) no-repeat; }
+              #search-dropdown .icon-#{tag.tagname}-redirect {
+                  background: url(class-icons/#{tag.tagname}-redirect.png) no-repeat; }
+              .doctabs .icon-#{tag.tagname} {
+                  background: url(class-icons/#{tag.tagname}.png) no-repeat; }
+            EOCSS
+          end
+          css.join("\n")
+        end
+
+        # Copies all class icons to given destination dir.
+        def write(dir)
+          FileUtils.mkdir(dir)
+
+          icons = {}
+          class_icon_providers.each do |tag|
+            icons[tag.class_icon[:small]] = "#{dir}/#{tag.tagname}.png"
+            icons[tag.class_icon[:large]] = "#{dir}/#{tag.tagname}-large.png"
+            icons[tag.class_icon[:redirect]] = "#{dir}/#{tag.tagname}-redirect.png"
+          end
+
+          icons.each_pair do |source, target|
+            if File.exists?(source)
+              FileUtils.cp(source, target)
+            else
+              Logger.warn(nil, "Class icon file not found", {:filename => source})
+            end
+          end
+        end
+
+        private
+
+        def class_icon_providers
+          @providers ||= generate_class_icon_providers
+        end
+
+        # Find tags with #class_icon and sort them from highest priority to lowest
+        def generate_class_icon_providers
+          TagRegistry.tags.find_all {|t| t.class_icon }.sort do |a, b|
+            a.class_icon[:priority] <=> b.class_icon[:priority]
+          end.reverse
+        end
+      end
+    end
+
+  end
+end

data/lib/jsduck/web/css.rb

@@ -1,5 +1,6 @@
 require 'jsduck/tag_registry'
 require 'jsduck/util/md5'
+require 'jsduck/web/class_icons'
 require 'jsduck/web/member_icons'
 
 module JsDuck
@@ -21,7 +22,17 @@ module JsDuck
       private
 
       def all_css
-        TagRegistry.css + Web::MemberIcons.css + @opts.css
+        [
+          css_from_tags,
+          Web::ClassIcons.css,
+          Web::MemberIcons.css,
+          @opts.css,
+        ].join
+      end
+
+      # Returns all the CSS gathered from @css attributes of tags.
+      def css_from_tags
+        TagRegistry.tags.map(&:css).compact.join("\n")
       end
     end
 

data/lib/jsduck/web/data.rb

@@ -1,8 +1,9 @@
 require 'jsduck/util/json'
 require 'jsduck/util/md5'
-require 'jsduck/web/icons'
+require 'jsduck/web/tree'
 require 'jsduck/web/search'
 require 'jsduck/tag_registry'
+require 'jsduck/member_registry'
 
 module JsDuck
   module Web
@@ -21,7 +22,7 @@ module JsDuck
       def write(filename)
         js = "Docs = " + Util::Json.generate({
           :data => {
-            :classes => Web::Icons.new.create(@relations.classes),
+            :classes => Web::Tree.create(@relations.classes),
             :guides => @assets.guides.to_array,
             :videos => @assets.videos.to_array,
             :examples => @assets.examples.to_array,
@@ -29,7 +30,7 @@ module JsDuck
             :guideSearch => @opts.search,
             :tests => @opts.tests,
             :signatures => TagRegistry.signatures,
-            :memberTypes => TagRegistry.member_types,
+            :memberTypes => MemberRegistry.definitions,
             :localStorageDb => @opts.local_storage_db,
             :showPrintButton => @opts.seo,
             :touchExamplesUi => @opts.touch_examples_ui,

data/lib/jsduck/web/index_html.rb

@@ -1,6 +1,7 @@
 require 'jsduck/logger'
 require 'jsduck/util/io'
 require 'jsduck/tag_registry'
+require 'jsduck/version'
 require 'fileutils'
 
 module JsDuck
@@ -19,12 +20,12 @@ module JsDuck
       # 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")
-          create_index_template_html(@opts.template_dir+"/index-template.html", @opts.output_dir+"/index-template.html")
+          FileUtils.cp(@opts.template+"/index.php", @opts.output+"/index.php")
+          create_template_html(@opts.template+"/template.html", @opts.output+"/template.html")
+          create_print_template_html(@opts.template+"/print-template.html", @opts.output+"/print-template.html")
+          create_index_template_html(@opts.template+"/index-template.html", @opts.output+"/index-template.html")
         else
-          create_template_html(@opts.template_dir+"/template.html", @opts.output_dir+"/index.html")
+          create_template_html(@opts.template+"/template.html", @opts.output+"/index.html")
         end
       end
 
@@ -33,9 +34,9 @@ module JsDuck
       def create_template_html(in_file, out_file)
         write_template(in_file, out_file, {
           "{title}" => @opts.title,
-          "{mobile_redirect}" => @opts.seo ? include_script(@opts.template_dir+"/mobile-redirect.js") : "",
-          "{header}" => @opts.header,
-          "{footer}" => "<div id='footer-content' style='display: none'>#{@opts.footer}</div>",
+          "{mobile_redirect}" => @opts.seo ? include_script(@opts.template+"/mobile-redirect.js") : "",
+          "{header}" => header,
+          "{footer}" => footer,
           "{extjs_path}" => @opts.extjs_path,
           "{data_path}" => File.basename(@paths[:data]),
           "{css_path}" => File.basename(@paths[:css]),
@@ -51,7 +52,7 @@ module JsDuck
       def create_print_template_html(in_file, out_file)
         write_template(in_file, out_file, {
           "{title}" => @opts.title,
-          "{header}" => @opts.header,
+          "{header}" => header,
           "{css_path}" => File.basename(@paths[:css]),
         })
       end
@@ -62,7 +63,7 @@ module JsDuck
 
         write_template(in_file, out_file, {
           "{title}" => @opts.title,
-          "{header}" => @opts.header,
+          "{header}" => header,
           "{categories}" => categories ? "<h1>API Documentation</h1> #{categories}" : "",
           "{guides}" => guides ? "<h1>Guides</h1> #{guides}" : "",
           "{css_path}" => File.basename(@paths[:css]),
@@ -73,6 +74,21 @@ module JsDuck
         "<script type='text/javascript'>\n" + Util::IO.read(filename) + "\n</script>"
       end
 
+      def header
+        @opts.title.sub(/^(.*?) +- +/, "<strong>\\1</strong> ")
+      end
+
+      def footer
+        jsduck = "<a href='https://github.com/senchalabs/jsduck'>JSDuck</a>"
+        date = Time.new.strftime('%a %d %b %Y %H:%M:%S')
+
+        footer_text = @opts.footer.gsub(/\{VERSION\}/, JsDuck::VERSION)
+          .gsub(/\{JSDUCK\}/, jsduck)
+          .gsub(/\{DATE\}/, date)
+
+        return "<div id='footer-content' style='display: none'>#{footer_text}</div>"
+      end
+
       # Opens in_file, replaces {keys} inside it, writes to out_file
       def write_template(in_file, out_file, replacements)
         Logger.log("Writing", out_file)

data/lib/jsduck/web/member_icons.rb

@@ -1,4 +1,4 @@
-require 'jsduck/tag_registry'
+require 'jsduck/member_registry'
 require 'fileutils'
 
 module JsDuck
@@ -29,13 +29,13 @@ module JsDuck
           if File.exists?(m[:icon])
             FileUtils.cp(m[:icon], "#{dir}/#{m[:name]}.png")
           else
-            Logger.warn(nil, "Member icon file not found", m[:icon])
+            Logger.warn(nil, "Member icon file not found", {:filename => m[:icon]})
           end
         end
       end
 
       def self.members_with_icons
-        TagRegistry.member_types.find_all {|m| m[:icon] }
+        MemberRegistry.definitions.find_all {|m| m[:icon] }
       end
     end
 

data/lib/jsduck/web/search.rb

@@ -1,4 +1,4 @@
-require 'jsduck/web/icons'
+require 'jsduck/web/class_icons'
 require 'jsduck/class_name'
 require 'jsduck/tag_registry'
 
@@ -52,7 +52,7 @@ module JsDuck
         return {
           :name => name,
           :fullName => alias_display_name(key)+": "+name,
-          :icon => Web::Icons::class_icon(cls) + "-redirect",
+          :icon => Web::ClassIcons.get(cls) + "-redirect",
           :url => "#!/api/" + cls[:name],
           :meta => combine_meta(cls),
           :sort => 0,
@@ -63,7 +63,7 @@ module JsDuck
         return {
           :name => ClassName.short(cls[:name]),
           :fullName => cls[:name],
-          :icon => Web::Icons::class_icon(cls),
+          :icon => Web::ClassIcons.get(cls),
           :url => "#!/api/" + cls[:name],
           :meta => combine_meta(cls),
           :sort => 1,
@@ -75,7 +75,7 @@ module JsDuck
           :name => ClassName.short(name),
           :fullName => name,
           :type => :class,
-          :icon => Web::Icons::class_icon(cls) + "-redirect",
+          :icon => Web::ClassIcons.get(cls) + "-redirect",
           :url => "#!/api/" + cls[:name],
           :meta => combine_meta(cls),
           :sort => 2,

data/lib/jsduck/web/source.rb

@@ -5,7 +5,7 @@ require 'fileutils'
 module JsDuck
   module Web
 
-    # Writes HTML JavaScript/CSS source into HTML files.
+    # Writes HTML JavaScript/SCSS source into HTML files.
     class Source
       def initialize(source_files)
         @source_files = source_files

data/lib/jsduck/web/template.rb

@@ -21,16 +21,16 @@ module JsDuck
 
       def write
         if @opts.template_links
-          Logger.log("Linking template files to", @opts.output_dir)
+          Logger.log("Linking template files to", @opts.output)
           move_files(:symlink)
         else
-          Logger.log("Copying template files to", @opts.output_dir)
+          Logger.log("Copying template files to", @opts.output)
           move_files(:cp_r)
         end
 
         # always copy the eg-iframe file.
-        eg_iframe = @opts.eg_iframe || @opts.template_dir+"/eg-iframe.html"
-        FileUtils.cp(eg_iframe, @opts.output_dir+"/eg-iframe.html")
+        eg_iframe = @opts.eg_iframe || @opts.template+"/eg-iframe.html"
+        FileUtils.cp(eg_iframe, @opts.output+"/eg-iframe.html")
       end
 
       private
@@ -38,8 +38,8 @@ module JsDuck
       # moves files from one dir to another using a method of FileUtils module.
       def move_files(method)
         @files.each do |file|
-          target = File.expand_path(@opts.output_dir)
-          Dir.glob(File.expand_path(@opts.template_dir+"/"+file)).each do |source|
+          target = File.expand_path(@opts.output)
+          Dir.glob(File.expand_path(@opts.template+"/"+file)).each do |source|
             FileUtils.send(method, source, target)
           end
         end