jsduck 5.0.0.beta01 → 5.0.0.beta2

data/lib/jsduck/tag/preventable.rb

@@ -16,7 +16,7 @@ module JsDuck::Tag
 
     # @preventable is optionally followed by some method name, but we
     # don't document it.
-    def parse_doc(p)
+    def parse_doc(p, pos)
       p.match(/.*$/)
       {:tagname => :preventable}
     end

data/lib/jsduck/tag/property.rb

@@ -6,6 +6,7 @@ module JsDuck::Tag
     def initialize
       @pattern = "property"
       @tagname = :property
+      @repeatable = true
       @member_type = {
         :name => :property,
         :category => :property_like,
@@ -19,7 +20,7 @@ module JsDuck::Tag
     end
 
     # @property {Type} [name=default] ...
-    def parse_doc(p)
+    def parse_doc(p, pos)
       tag = p.standard_tag({:tagname => :property, :type => true, :name => true})
       tag[:doc] = :multiline
       tag
@@ -27,13 +28,16 @@ module JsDuck::Tag
 
     def process_doc(h, tags, pos)
       p = tags[0]
-      h[:name] = p[:name]
       # Type might also come from @type, don't overwrite it with nil.
       h[:type] = p[:type] if p[:type]
       h[:default] = p[:default]
-      h[:properties] = JsDuck::Doc::Subproperties.nest(tags, pos)[0][:properties]
+
       # Documentation after the first @property is part of the top-level docs.
       h[:doc] += p[:doc]
+
+      nested = JsDuck::Doc::Subproperties.nest(tags, pos)[0]
+      h[:properties] = nested[:properties]
+      h[:name] = nested[:name]
     end
   end
 end

data/lib/jsduck/tag/ptype.rb

@@ -4,10 +4,11 @@ module JsDuck::Tag
   class Ptype < Xtype
     def initialize
       @pattern = "ptype"
+      @repeatable = true
     end
 
     # @ptype name
-    def parse_doc(p)
+    def parse_doc(p, pos)
       {
         :tagname => :aliases,
         :name => parse_alias_shorthand(p, "plugin")

data/lib/jsduck/tag/requires.rb

@@ -5,6 +5,7 @@ module JsDuck::Tag
     def initialize
       @pattern = "requires"
       @tagname = :requires
+      @repeatable = true
       @ext_define_pattern = "requires"
       @ext_define_default = {:requires => []}
     end

data/lib/jsduck/tag/return.rb

@@ -7,11 +7,12 @@ module JsDuck::Tag
     def initialize
       @pattern = ["return", "returns"]
       @tagname = :return
+      @repeatable = true
       @html_position = POS_RETURN
     end
 
     # @return {Type} return.name ...
-    def parse_doc(p)
+    def parse_doc(p, pos)
       tag = p.standard_tag({:tagname => :return, :type => true})
       tag[:name] = subproperty_name(p)
       tag[:doc] = :multiline

data/lib/jsduck/tag/since.rb

@@ -9,7 +9,7 @@ module JsDuck::Tag
       @html_position = POS_SINCE
     end
 
-    def parse_doc(p)
+    def parse_doc(p, pos)
       {
         :tagname => :since,
         :version => p.match(/.*$/).strip,
@@ -17,10 +17,6 @@ module JsDuck::Tag
     end
 
     def process_doc(h, tags, pos)
-      if tags.length > 1
-        JsDuck::Logger.warn(nil, "Only one @since tag allowed per class/member.")
-      end
-
       h[:since] = tags[0][:version]
     end
 

data/lib/jsduck/tag/tag.rb

@@ -6,6 +6,11 @@ module JsDuck::Tag
     # For example: "cfg"
     attr_reader :pattern
 
+    # Set to true to allow the tag to occour multiple times within one
+    # doc-comment.  By default a tag can only appear once and when
+    # it's detected several times a warning will be generated.
+    attr_reader :repeatable
+
     # Called by DocParser when the @tag is reached to do the parsing
     # from that point forward.  Gets passed an instance of DocScanner.
     #
@@ -23,7 +28,10 @@ module JsDuck::Tag
     # the documentation following this tag will get added to the :doc
     # field of the tag and will later be accessible in #process_doc
     # method.
-    def parse_doc(p)
+    #
+    # Also a hash with position information {:filename, :linenr} is
+    # passed in.
+    def parse_doc(scanner, position)
     end
 
     # Defines the symbol under which the tag data is stored in final
@@ -163,17 +171,18 @@ module JsDuck::Tag
     POS_ASIDE = 1
     POS_PRIVATE = 2
     POS_DOC = 3
-    POS_DEFAULT = 4
-    POS_SINCE = 5
-    POS_DEPRECATED = 6
-    POS_ENUM = 7
-    POS_TEMPLATE = 8
-    POS_PREVENTABLE = 9
-    POS_PARAM = 10
-    POS_SUBPROPERTIES = 11
-    POS_RETURN = 12
-    POS_THROWS = 13
-    POS_OVERRIDES = 14
+    POS_LOCALDOC = 4
+    POS_DEFAULT = 5
+    POS_SINCE = 6
+    POS_DEPRECATED = 7
+    POS_ENUM = 8
+    POS_TEMPLATE = 9
+    POS_PREVENTABLE = 10
+    POS_PARAM = 11
+    POS_SUBPROPERTIES = 12
+    POS_RETURN = 13
+    POS_THROWS = 14
+    POS_OVERRIDES = 15
 
     # Called before #to_html to allow rendering of Markdown content.
     # For this an instance of DocFormatter is passed in, on which one

data/lib/jsduck/tag/throws.rb

@@ -6,11 +6,12 @@ module JsDuck::Tag
     def initialize
       @pattern = "throws"
       @tagname = :throws
+      @repeatable = true
       @html_position = POS_THROWS
     end
 
     # @throws {Type} ...
-    def parse_doc(p)
+    def parse_doc(p, pos)
       tag = p.standard_tag({:tagname => :throws, :type => true})
       tag[:doc] = :multiline
       tag

data/lib/jsduck/tag/type.rb

@@ -18,7 +18,7 @@ module JsDuck::Tag
     # The presence of @type implies that we are dealing with property.
     # ext-doc allows type name to be either inside curly braces or
     # without them at all.
-    def parse_doc(p)
+    def parse_doc(p, pos)
       tag = p.standard_tag({:tagname => :type, :type => true})
       tag[:type] = curlyless_type(p) unless tag[:type]
       tag
@@ -34,7 +34,7 @@ module JsDuck::Tag
 
     # Do the merging of :type field
     def merge(h, docs, code)
-      h[:type] = JsDuck::DocsCodeComparer.merge_if_matches(:type, docs, code)
+      JsDuck::DocsCodeComparer.merge_if_matches(h, :type, docs, code)
       if h[:type] == nil
         h[:type] = code[:tagname] == :method ? "Function" : "Object"
       end

data/lib/jsduck/tag/uses.rb

@@ -5,6 +5,7 @@ module JsDuck::Tag
     def initialize
       @pattern = "uses"
       @tagname = :uses
+      @repeatable = true
       @ext_define_pattern = "uses"
       @ext_define_default = {:uses => []}
     end

data/lib/jsduck/tag/xtype.rb

@@ -6,10 +6,11 @@ module JsDuck::Tag
     def initialize
       @pattern = "xtype"
       @ext_define_pattern = "xtype"
+      @repeatable = true
     end
 
     # @xtype name
-    def parse_doc(p)
+    def parse_doc(p, pos)
       {
         :tagname => :aliases,
         :name => parse_alias_shorthand(p, "widget")

data/lib/jsduck/tag_loader.rb

@@ -2,35 +2,46 @@ require "jsduck/tag/tag"
 
 module JsDuck
 
+  # Loads Tag classes from the builtin tags/ dir and optionally also
+  # from additional paths.
   class TagLoader
-    def initialize
-      @already_loaded = {}
+    def initialize(extra_paths=[])
+      @paths = [File.dirname(__FILE__) + "/tag"]
+      @paths += extra_paths
     end
 
-    # Loads tag classes from given dir or single file.
+    # Loads Tag classes from all supplied paths.
     #
     # Returns the tag classes that got loaded, sorted alphabetically
-    # by class name. This ensures attributes in member signatures are
-    # always rendered in the same order.
-    def load_from(path)
+    # by class name.
+    def load_all
+      @paths.each {|path| load(path) }
+      tag_classes
+    end
+
+    private
+
+    # Loads tag classes from given dir or single file.
+    def load(path)
       if File.directory?(path)
-        Dir[path+"/**/*.rb"].each {|file| require(file) }
+        Dir[path+"/**/*.rb"].each do |file|
+          # Ruby 1.8 doesn't understand that "jsduck/tag/tag" and
+          # "./lib/jsduck/tag/tag.rb" refer to the same file.  So
+          # explicitly avoid loading this file (as it's required on
+          # top already) to prevent warnings of constants getting
+          # defined multiple times.
+          require(file) unless file =~ /jsduck\/tag\/tag\.rb$/
+        end
       else
         require(path)
       end
-
-      tag_classes
     end
 
-    private
-
     def tag_classes
       classes = JsDuck::Tag::Tag.descendants
-      # exclude already loaded classes
-      classes.reject! {|cls| @already_loaded[cls.name] }
-      # remember these classes as loaded
-      classes.each {|cls| @already_loaded[cls.name] = true }
       # sort by classname
+      # This ensures attributes in member signatures are
+      # always rendered in the same order.
       classes.sort {|a, b| a.name <=> b.name }
     end
 

data/lib/jsduck/tag_registry.rb

@@ -1,13 +1,28 @@
 require "jsduck/tag_loader"
-require "jsduck/util/singleton"
 
 module JsDuck
 
   # Access to builtin @tags
   class TagRegistry
-    include Util::Singleton
+    # Access to the singleton instance (only used internally)
+    def self.instance
+      @instance = TagRegistry.new unless @instance
+      @instance
+    end
+
+    # Reconfigures the registry with additional load paths.
+    # Used in Options class.
+    def self.reconfigure(load_paths)
+      @instance = TagRegistry.new(load_paths)
+    end
 
-    def initialize
+    # Redirect calls from TagRegistry.method to TagRegistry.instance.method,
+    # making it behave like other Singleton classes.
+    def self.method_missing(meth, *args, &block)
+      self.instance.send(meth, *args, &block)
+    end
+
+    def initialize(load_paths=[])
       @patterns = {}
       @ext_define_patterns = {}
       @ext_define_defaults = {}
@@ -19,13 +34,7 @@ module JsDuck
       @member_types = []
       @css = []
 
-      @loader = TagLoader.new
-      load_from(File.dirname(__FILE__) + "/tag")
-    end
-
-    # Loads and instantiates tags from the given file or dir.
-    def load_from(path)
-      instantiate_tags(@loader.load_from(path))
+      instantiate_tags(TagLoader.new(load_paths).load_all)
     end
 
     # Instantiates all descendants of JsDuck::Tag::Tag
@@ -171,7 +180,7 @@ module JsDuck
       expand_merger(:member)
       expand_merger(:method_like)
       expand_merger(:property_like)
-      @mergers_expanded
+      @mergers_expanded = true
     end
 
     def expand_merger(type_name)

data/lib/jsduck/web/css.rb

@@ -0,0 +1,22 @@
+require 'jsduck/tag_registry'
+require 'jsduck/util/md5'
+
+module JsDuck
+  module Web
+
+    # Writes the CSS gathered from Tag classes and --css option into given file.
+    # Then Renames the file so it contains an MD5 hash inside it,
+    # returning the resulting fingerprinted name.
+    class Css
+      def initialize(opts)
+        @opts = opts
+      end
+
+      def write(filename)
+        File.open(filename, 'w') {|f| f.write(TagRegistry.css + @opts.css) }
+        Util::MD5.rename(filename)
+      end
+    end
+
+  end
+end

data/lib/jsduck/web/data.rb

@@ -0,0 +1,50 @@
+require 'jsduck/util/json'
+require 'jsduck/util/md5'
+require 'jsduck/web/icons'
+require 'jsduck/web/search'
+require 'jsduck/tag_registry'
+
+module JsDuck
+  module Web
+
+    # Creates big JS file with data for Docs app.
+    class Data
+      def initialize(relations, assets, opts)
+        @relations = relations
+        @assets = assets
+        @opts = opts
+      end
+
+      # Writes classes, guides, videos, and search data to one big .js file.
+      # Then Renames the file so it contains an MD5 hash inside it,
+      # returning the resulting fingerprinted name.
+      def write(filename)
+        js = "Docs = " + Util::Json.generate({
+          :data => {
+            :classes => Web::Icons.new.create(@relations.classes),
+            :guides => @assets.guides.to_array,
+            :videos => @assets.videos.to_array,
+            :examples => @assets.examples.to_array,
+            :search => Web::Search.new.create(@relations.classes, @assets),
+            :tests => @opts.tests,
+            :signatures => TagRegistry.signatures,
+            :memberTypes => TagRegistry.member_types,
+            :localStorageDb => @opts.local_storage_db,
+            :showPrintButton => @opts.seo,
+            :touchExamplesUi => @opts.touch_examples_ui,
+            :source => @opts.source,
+            :commentsUrl => @opts.comments_url,
+            :commentsDomain => @opts.comments_domain,
+            :message => @opts.message,
+          }
+        }) + ";\n"
+
+        File.open(filename, 'w') {|f| f.write(js) }
+
+        Util::MD5.rename(filename)
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/web/icons.rb

@@ -0,0 +1,31 @@
+module JsDuck
+  module Web
+
+    # Creates an array of small hashes documenting name, parent class
+    # and icon of a class.
+    class Icons
+      def create(classes)
+        classes.map do |cls|
+          {
+            :name => cls[:name],
+            :extends => cls[:extends],
+            :private => cls[:private],
+            :icon => Web::Icons::class_icon(cls),
+          }
+        end
+      end
+
+      # Returns CSS class name for an icon of class
+      def self.class_icon(cls)
+        if cls[:singleton]
+          "icon-singleton"
+        elsif cls.inherits_from?("Ext.Component")
+          "icon-component"
+        else
+          "icon-class"
+        end
+      end
+    end
+
+  end
+end

data/lib/jsduck/web/index_html.rb

@@ -0,0 +1,88 @@
+require 'jsduck/logger'
+require 'jsduck/util/io'
+require 'jsduck/tag_registry'
+require 'fileutils'
+
+module JsDuck
+  module Web
+
+    # Deals with creation of main HTML or PHP files.
+    class IndexHtml
+      def initialize(assets, opts, paths={})
+        @assets = assets
+        @opts = opts
+        @paths = paths
+      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")
+          create_index_template_html(@opts.template_dir+"/index-template.html", @opts.output_dir+"/index-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,
+          "{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>",
+          "{extjs_path}" => @opts.extjs_path,
+          "{data_path}" => File.basename(@paths[:data]),
+          "{css_path}" => File.basename(@paths[:css]),
+          "{welcome}" => @assets.welcome.to_html("display:none"),
+          "{categories}" => @assets.categories.to_html("display:none"),
+          "{guides}" => @assets.guides.to_html("display:none"),
+          "{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,
+          "{css_path}" => File.basename(@paths[:css]),
+        })
+      end
+
+      def create_index_template_html(in_file, out_file)
+        categories = @assets.categories.to_html
+        guides = @assets.guides.to_html
+
+        write_template(in_file, out_file, {
+          "{title}" => @opts.title,
+          "{header}" => @opts.header,
+          "{categories}" => categories ? "<h1>API Documentation</h1> #{categories}" : "",
+          "{guides}" => guides ? "<h1>Guides</h1> #{guides}" : "",
+          "{css_path}" => File.basename(@paths[:css]),
+        })
+      end
+
+      def include_script(filename)
+        "<script type='text/javascript'>\n" + Util::IO.read(filename) + "\n</script>"
+      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)
+        html = Util::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
+end