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

jsduck 3.1.0 → 3.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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