RubyGems - jsduck - Versions diffs - 3.1.0 → 3.2.1 - Mend

jsduck 3.1.0 → 3.2.1

Files changed (41) hide show

data/README.md +14 -9
data/Rakefile +31 -230
data/jsduck.gemspec +2 -2
data/lib/jsduck/accessors.rb +14 -6
data/lib/jsduck/aggregator.rb +9 -4
data/lib/jsduck/app.rb +1 -0
data/lib/jsduck/app_data.rb +14 -7
data/lib/jsduck/app_exporter.rb +3 -3
data/lib/jsduck/class.rb +8 -5
data/lib/jsduck/class_formatter.rb +1 -3
data/lib/jsduck/css_parser.rb +1 -1
data/lib/jsduck/doc_formatter.rb +140 -36
data/lib/jsduck/doc_parser.rb +27 -44
data/lib/jsduck/index_html.rb +0 -3
data/lib/jsduck/inherit_doc.rb +20 -4
data/lib/jsduck/js_parser.rb +1 -1
data/lib/jsduck/lint.rb +15 -0
data/lib/jsduck/logger.rb +9 -7
data/lib/jsduck/merger.rb +18 -16
data/lib/jsduck/meta_tag.rb +28 -5
data/lib/jsduck/meta_tag_loader.rb +38 -21
data/lib/jsduck/meta_tag_registry.rb +79 -0
data/lib/jsduck/options.rb +69 -12
data/lib/jsduck/renderer.rb +10 -38
data/lib/jsduck/search_data.rb +53 -3
data/lib/jsduck/tag/abstract.rb +14 -0
data/lib/jsduck/{author_tag.rb → tag/author.rb} +2 -2
data/lib/jsduck/tag/deprecated.rb +33 -0
data/lib/jsduck/{doc_author_tag.rb → tag/docauthor.rb} +2 -2
data/lib/jsduck/tag/markdown.rb +12 -0
data/lib/jsduck/tag/preventable.rb +28 -0
data/lib/jsduck/tag/protected.rb +14 -0
data/lib/jsduck/tag/readonly.rb +14 -0
data/lib/jsduck/tag/required.rb +21 -0
data/lib/jsduck/tag/static.rb +14 -0
data/lib/jsduck/tag/template.rb +23 -0
data/opt/example.js +149 -0
metadata +17 -9
data/opt/extjs-welcome.html +0 -74
data/opt/touch-iframe.html +0 -85
data/opt/touch-welcome.html +0 -122

data/lib/jsduck/options.rb CHANGED Viewed

@@ -1,5 +1,5 @@
 require 'optparse'
-require 'jsduck/meta_tag_loader'
+require 'jsduck/meta_tag_registry'
 require 'jsduck/logger'
 module JsDuck
@@ -11,7 +11,6 @@ module JsDuck
     attr_accessor :output_dir
     attr_accessor :ignore_global
     attr_accessor :external_classes
-    attr_accessor :meta_tags
     # Customizing output
     attr_accessor :title
@@ -70,10 +69,9 @@ module JsDuck
         # Special anything-goes type
         "Mixed",
       ]
-      @meta_tags = []
       @meta_tag_paths = []
-      @version = "3.1.0"
+      @version = "3.2.1"
       # Customizing output
       @title = "Sencha Docs - Ext JS"
@@ -107,6 +105,10 @@ module JsDuck
       @local_storage_db = "docs"
       @touch_examples_ui = false
       @ext_namespaces = ["Ext"]
+      # enable all warnings except :link_auto
+      Logger.instance.set_warning(:all, true)
+      Logger.instance.set_warning(:link_auto, false)
     end
     # Make options object behave like hash.
@@ -120,11 +122,11 @@ module JsDuck
         read_filenames(canonical(fname))
       end
       validate
-      @meta_tags = MetaTagLoader.new.load(@meta_tag_paths)
+      MetaTagRegistry.instance.load([:builtins] + @meta_tag_paths)
     end
     def create_option_parser
-      return OptionParser.new do | opts |
+      optparser = OptionParser.new do | opts |
         opts.banner = "Usage: jsduck [options] files/dirs...\n\n"
         opts.on('-o', '--output=PATH',
@@ -157,7 +159,9 @@ module JsDuck
         end
         opts.on('--no-warnings',
-          "Turns off all warnings. Same as --warnings=-all", " ") do
+          "Turns off all warnings.",
+          "(Deprecated, use --warnings=-all instead.)", " ") do
+          Logger.instance.warn(nil, "--no-warnings is deprecated. Use --warnings=-all instead.")
           Logger.instance.set_warning(:all, false)
         end
@@ -177,8 +181,8 @@ module JsDuck
         opts.on('--footer=TEXT',
           "Custom footer text for the documentation.",
-          "Defaults to: 'Generated with JSDuck.'", " ") do |text|
-          @footer = text
+          "Defaults to: 'Generated with JSDuck {VERSION}.'", " ") do |text|
+          @footer = text.gsub(/\{VERSION\}/, @version)
         end
         opts.on('--head-html=HTML', "HTML to append to the <head> section of index.html.", " ") do |html|
@@ -277,8 +281,10 @@ module JsDuck
         opts.on('--warnings=+A,-B,+C', Array,
           "Turns warnings selectively on/off.",
-          "+foo turns on a warning, -foo turns it off.",
-          "Possible warning types are:",
+          " ",
+          " +all - to turn on all warnings",
+          " ",
+          "By default these warnings are turned +on/-off:",
           " ",
           *Logger.instance.doc_warnings) do |warnings|
           warnings.each do |op|
@@ -332,6 +338,17 @@ module JsDuck
           @ext_namespaces = ns
         end
+        opts.on('--config=PATH',
+          "Loads config options from JSON file.", " ") do |path|
+          path = canonical(path)
+          config = read_json_config(path)
+          # treat paths inside JSON config relative to the location of
+          # config file.  When done, switch back to current working dir.
+          @working_dir = File.dirname(path)
+          optparser.parse!(config).each {|fname| read_filenames(canonical(fname)) }
+          @working_dir = nil
+        end
         opts.on('-h', '--help[=full]',
           "Short help or --help=full for all available options.", " ") do |v|
           if v == 'full'
@@ -378,6 +395,31 @@ module JsDuck
           exit
         end
       end
+      return optparser
+    end
+    # Reads JSON configuration from file and returns an array of
+    # config options that can be feeded into optparser.
+    def read_json_config(fname)
+      config = []
+      json = JsonDuck.read(fname)
+      json.each_pair do |key, value|
+        if key == "--"
+          # filenames
+          config += Array(value).map(&:to_s)
+        elsif value == true
+          # simple switch
+          config += [key.to_s]
+        else
+          # An option with value or with multiple values.
+          # In the latter case, add the option multiple times.
+          Array(value).each do |v|
+            config += [key.to_s, v.to_s]
+          end
+        end
+      end
+      config
     end
     # scans directory for .js files or simply adds file to input files list
@@ -385,6 +427,8 @@ module JsDuck
       if File.exists?(fname)
         if File.directory?(fname)
           Dir[fname+"/**/*.{js,css,scss}"].each {|f| @input_files << f }
+        elsif fname =~ /\.jsb3$/
+          @input_files += extract_jsb_files(fname)
         else
           @input_files << fname
         end
@@ -393,13 +437,26 @@ module JsDuck
       end
     end
+    # Extracts files of first build in jsb file
+    def extract_jsb_files(jsb_file)
+      json = JSON.parse(IO.read(jsb_file))
+      basedir = File.dirname(jsb_file)
+      return json["builds"][0]["packages"].map do |package_id|
+        package = json["packages"].find {|p| p["id"] == package_id }
+        (package ? package["files"] : []).map do |file|
+          File.expand_path(basedir + "/" + file["path"] + file["name"])
+        end
+      end.flatten
+    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)
+      File.expand_path(path, @working_dir)
     end
     # Runs checks on the options

data/lib/jsduck/renderer.rb CHANGED Viewed

@@ -1,3 +1,4 @@
+require 'jsduck/meta_tag_registry'
 require 'cgi'
 module JsDuck
@@ -5,12 +6,13 @@ module JsDuck
   # Ruby-side implementation of class docs Renderer.
   # Uses PhantomJS to run Docs.Renderer JavaScript.
   class Renderer
-    # List of meta-tag implementations
-    attr_accessor :meta_tags
     def render(cls)
         @cls = cls
+        # Set doc-formatter context to this class
+        MetaTagRegistry.instance.formatter.class_context = @cls[:name]
+        MetaTagRegistry.instance.formatter.doc_context = @cls[:files][0]
         return [
           "<div>",
             render_sidebar,
@@ -38,8 +40,8 @@ module JsDuck
     def render_meta_data(meta_data)
       return if meta_data.size == 0
-      @meta_tags.map do |tag|
-        contents = meta_data[tag.name]
+      MetaTagRegistry.instance.tags.map do |tag|
+        contents = meta_data[tag.key]
         if contents
           tag.to_html(contents)
         else
@@ -221,20 +223,8 @@ module JsDuck
       end
       after = ""
-      if m[:protected]
-        after += "<strong class='protected signature'>protected</strong>"
-      end
-      if m[:static]
-        after += "<strong class='static signature'>static</strong>"
-      end
-      if m[:deprecated]
-        after += "<strong class='deprecated signature'>deprecated</strong>"
-      end
-      if m[:required]
-        after += "<strong class='required signature'>required</strong>"
-      end
-      if m[:template]
-        after += "<strong class='template signature'>template</strong>"
+      MetaTagRegistry.instance.signatures.each do |s|
+        after += "<strong class='#{s[:key]} signature'>#{s[:long]}</strong>" if m[:meta][s[:key]]
       end
       uri = "#!/api/#{m[:owner]}-#{m[:id]}"
@@ -259,25 +249,7 @@ module JsDuck
         doc << "<p>Defaults to: <code>" + CGI.escapeHTML(m[:default]) + "</code></p>"
       end
-      if m[:deprecated]
-        v = m[:deprecated][:version] ? "since " + m[:deprecated][:version] : ""
-        doc << [
-          "<div class='signature-box deprecated'>",
-          "<p>This #{m[:tagname]} has been <strong>deprecated</strong> #{v}</p>",
-          m[:deprecated][:text],
-          "</div>",
-        ]
-      end
-      if m[:template]
-        doc << [
-          "<div class='signature-box 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
+      MetaTagRegistry.instance.formatter.doc_context = m[:files][0]
       doc << render_meta_data(m[:meta])
       doc << render_params_and_return(m)

data/lib/jsduck/search_data.rb CHANGED Viewed

@@ -10,6 +10,17 @@ module JsDuck
       list = []
       docs.each do |cls|
         list << class_node(cls)
+        cls[:alternateClassNames].each do |name|
+          list << alt_node(name, cls)
+        end
+        cls[:aliases].each_pair do |key, items|
+          items.each do |name|
+            list << alias_node(key, name, cls)
+          end
+        end
         [:members, :statics].each do |group|
           cls[group].each_key do |type|
             cls.members(type, group).each do |m|
@@ -24,13 +35,39 @@ module JsDuck
       list
     end
+    # Creates structure representing one alias
+    def alias_node(key, name, cls)
+      return {
+        :cls => alias_display_name(key)+": "+name,
+        :member => name,
+        :type => :class,
+        :icon => :subclass,
+        :id => cls.full_name,
+        :sort => 0,
+      }
+    end
     # Creates structure representing one class
     def class_node(cls)
       return {
         :cls => cls.full_name,
         :member => cls.short_name,
         :type => :class,
-        :aliases => cls[:aliases]
+        :icon => :class,
+        :id => cls.full_name,
+        :sort => 1,
+      }
+    end
+    # Creates structure representing one alternate classname
+    def alt_node(name, cls)
+      return {
+        :cls => name,
+        :member => Class.short_name(name),
+        :type => :class,
+        :icon => :subclass,
+        :id => cls.full_name,
+        :sort => 2,
       }
     end
@@ -39,9 +76,22 @@ module JsDuck
       return {
         :cls => cls.full_name,
         :member => member[:name],
-        :type => member[:tagname],
-        :id => member[:id],
+        :type => :member,
+        :icon => member[:tagname],
+        :id => cls.full_name + "-" + member[:id],
+        :sort => 3,
+      }
+    end
+    # Some alias types are shown differently.
+    # e.g. instead of "widget:" we show "xtype:"
+    def alias_display_name(key)
+      titles = {
+        "widget" => "xtype",
+        "plugin" => "ptype",
+        "feature" => "ftype",
       }
+      titles[key] || key
     end
   end

data/lib/jsduck/tag/abstract.rb ADDED Viewed

@@ -0,0 +1,14 @@
+require "jsduck/meta_tag"
+module JsDuck::Tag
+  # Implementation of @abstract tag
+  class Abstract < JsDuck::MetaTag
+    def initialize
+      @name = "abstract"
+      @key = :abstract
+      @signature = {:long => "abstract", :short => "ABS"}
+      @boolean = true
+    end
+  end
+end

data/lib/jsduck/{author_tag.rb → tag/author.rb} RENAMED Viewed

@@ -1,8 +1,8 @@
 require "jsduck/meta_tag"
-module JsDuck
+module JsDuck::Tag
   # Implementation of hidden @author tag
-  class AuthorTag < MetaTag
+  class Author < JsDuck::MetaTag
     def initialize
       @name = "author"
     end

data/lib/jsduck/tag/deprecated.rb ADDED Viewed

@@ -0,0 +1,33 @@
+require "jsduck/meta_tag"
+module JsDuck::Tag
+  # Implementation of @deprecated tag
+  class Deprecated < JsDuck::MetaTag
+    def initialize
+      @name = "deprecated"
+      @key = :deprecated
+      @signature = {:long => "deprecated", :short => "DEP"}
+      @multiline = true
+    end
+    def to_value(contents)
+      text = contents[0]
+      if text =~ /\A([0-9.]+)(.*)\Z/
+        {:version => $1, :text => $2.strip}
+      else
+        {:text => text || ""}
+      end
+    end
+    def to_html(depr)
+      v = depr[:version] ? "since " + depr[:version] : ""
+      <<-EOHTML
+        <div class='signature-box deprecated'>
+        <p>This member has been <strong>deprecated</strong> #{v}</p>
+        #{format(depr[:text])}
+        </div>
+      EOHTML
+    end
+  end
+end

data/lib/jsduck/{doc_author_tag.rb → tag/docauthor.rb} RENAMED Viewed

@@ -1,8 +1,8 @@
 require "jsduck/meta_tag"
-module JsDuck
+module JsDuck::Tag
   # Implementation of hidden @docauthor tag
-  class DocAuthorTag < MetaTag
+  class Docauthor < JsDuck::MetaTag
     def initialize
       @name = "docauthor"
     end

data/lib/jsduck/tag/markdown.rb ADDED Viewed

@@ -0,0 +1,12 @@
+require "jsduck/meta_tag"
+module JsDuck::Tag
+  # A @markdown tag that is simply ignored
+  class Markdown < JsDuck::MetaTag
+    def initialize
+      @name = "markdown"
+      @boolean = true
+    end
+  end
+end

data/lib/jsduck/tag/preventable.rb ADDED Viewed

@@ -0,0 +1,28 @@
+require "jsduck/meta_tag"
+module JsDuck::Tag
+  # Implementation of @preventable tag
+  class Preventable < JsDuck::MetaTag
+    def initialize
+      @name = "preventable"
+      @key = :preventable
+      @signature = {:long => "preventable", :short => "PREV"}
+    end
+    # @preventable is optionally followed by some method name, but we
+    # don't document it.
+    def to_value(contents)
+      true
+    end
+    def to_html(v)
+      <<-EOHTML
+        <div class='signature-box preventable'>
+        <p>This action following this event is <b>preventable</b>.
+        When any of the listeners returns false, the action is cancelled.</p>
+        </div>
+      EOHTML
+    end
+  end
+end