jsduck 4.10.4 → 5.0.0.beta01

data/lib/jsduck/render/subproperties.rb

@@ -0,0 +1,99 @@
+require 'jsduck/util/html'
+require 'jsduck/util/singleton'
+
+module JsDuck
+  module Render
+
+    # Renders params, return values and everything else that can have
+    # nested subproperties.
+    class Subproperties
+      include Util::Singleton
+
+      # Renders object properties, which could also be functions in
+      # which case they will be rendered with parameters and return
+      # value.
+      def render(item)
+        doc = []
+
+        if item[:type] == "Function"
+          params = item[:properties]
+          # If the name of last property is "return" remove it from
+          # properties list and format as a return value afterwards.
+          if item[:properties].last[:name] == "return"
+            ret = params.last
+            params = params.slice(0, params.length-1)
+          end
+
+          doc << render_params(params)
+          doc << render_return(ret) if ret
+        else
+          doc << render_list(item[:properties])
+        end
+
+        doc
+      end
+
+      def render_params(params)
+        return [
+          '<h3 class="pa">Parameters</h3>',
+          render_list(params),
+        ]
+      end
+
+      def render_list(params)
+        return [
+          "<ul>",
+          params.map {|p| render_single_param(p) },
+          "</ul>",
+        ]
+      end
+
+      def render_single_param(p)
+        return [
+          "<li>",
+            "<span class='pre'>#{p[:name]}</span> : ",
+            p[:html_type],
+            p[:optional] ? " (optional)" : "",
+            "<div class='sub-desc'>",
+              p[:doc],
+              p[:default] ? "<p>Defaults to: <code>#{Util::HTML.escape(p[:default])}</code></p>" : "",
+              p[:properties] && p[:properties].length > 0 ? render(p) : "",
+            "</div>",
+          "</li>",
+        ]
+      end
+
+      def render_return(ret)
+        return [
+          "<h3 class='pa'>Returns</h3>",
+          "<ul>",
+            "<li>",
+              "<span class='pre'>#{ret[:html_type]}</span>",
+              "<div class='sub-desc'>",
+                ret[:doc],
+                ret[:properties] && ret[:properties].length > 0 ? render(ret) : "",
+              "</div>",
+            "</li>",
+          "</ul>",
+        ]
+      end
+
+      def render_throws(throws)
+        return [
+          "<h3 class='pa'>Throws</h3>",
+          "<ul>",
+            throws.map do |thr|
+              [
+                "<li>",
+                  "<span class='pre'>#{thr[:html_type]}</span>",
+                  "<div class='sub-desc'>#{thr[:doc]}</div>",
+                "</li>",
+              ]
+            end,
+          "</ul>",
+        ]
+      end
+    end
+
+  end
+end

data/lib/jsduck/render/tags.rb

@@ -0,0 +1,38 @@
+require 'jsduck/tag_registry'
+
+module JsDuck
+  module Render
+
+    # Performs the rendering of tags.
+    class Tags
+      # Renders tags of a particular section.
+      #
+      # Takes member or class hash.
+      # Returns array of rendered HTML.
+      def self.render(member)
+        TagRegistry.html_renderers.map do |tag|
+          if member[tag.tagname]
+            tag.to_html(member)
+          else
+            nil
+          end
+        end
+      end
+
+      # Renders the signatures for a class member.
+      # Returns a string.
+      def self.render_signature(member)
+        html = []
+        TagRegistry.signatures.each do |s|
+          if member[s[:tagname]]
+            title = s[:tooltip] ? "title='#{s[:tooltip]}'" : ""
+            html << "<span class='#{s[:tagname]}' #{title}>#{s[:long]}</span>"
+          end
+        end
+        '<span class="signature">' + html.join + "</span>"
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/search_data.rb

@@ -1,5 +1,6 @@
 require 'jsduck/icons'
 require 'jsduck/class_name'
+require 'jsduck/tag_registry'
 
 module JsDuck
 
@@ -8,7 +9,7 @@ module JsDuck
   class SearchData
     # Given list of classes and other assets, returns an array of
     # hashes describing the search data.
-    def create(classes, assets, opts)
+    def create(classes, assets)
       list = []
 
       classes.each do |cls|
@@ -24,14 +25,13 @@ module JsDuck
           end
         end
 
-        # add all local members, but skip hidden members and constructors
+        # add all local members, but skip constructors
         cls[:members].each do |m|
-          list << member_node(m, cls) unless m[:meta][:hide] || constructor?(m)
+          list << member_node(m, cls) unless m[:name] == ClassName.short(cls[:name])
         end
       end
 
-      # Don't include guides data when separate guides search engine is provided
-      assets.guides.each_item {|g| list << guide_node(g) } unless opts.search[:url]
+      assets.guides.each_item {|g| list << guide_node(g) }
 
       assets.videos.each_item {|v| list << video_node(v) }
 
@@ -42,17 +42,13 @@ module JsDuck
 
     private
 
-    def constructor?(m)
-      m[:tagname] == :method && m[:name] == "constructor"
-    end
-
     def alias_node(key, name, cls)
       return {
         :name => name,
         :fullName => alias_display_name(key)+": "+name,
         :icon => Icons::class_icon(cls) + "-redirect",
         :url => "#!/api/" + cls[:name],
-        :meta => cls[:meta],
+        :meta => combine_meta(cls),
         :sort => 0,
       }
     end
@@ -63,7 +59,7 @@ module JsDuck
         :fullName => cls[:name],
         :icon => Icons::class_icon(cls),
         :url => "#!/api/" + cls[:name],
-        :meta => cls[:meta],
+        :meta => combine_meta(cls),
         :sort => 1,
       }
     end
@@ -75,7 +71,7 @@ module JsDuck
         :type => :class,
         :icon => Icons::class_icon(cls) + "-redirect",
         :url => "#!/api/" + cls[:name],
-        :meta => cls[:meta],
+        :meta => combine_meta(cls),
         :sort => 2,
       }
     end
@@ -86,7 +82,7 @@ module JsDuck
         :fullName => cls[:name] + "." + member[:name],
         :icon => "icon-" + member[:tagname].to_s,
         :url => "#!/api/" + cls[:name] + "-" + member[:id],
-        :meta => member[:meta],
+        :meta => combine_meta(member),
         :sort => 3,
       }
     end
@@ -124,6 +120,16 @@ module JsDuck
       }
     end
 
+    # Add data for builtin tags with signatures to :meta field.
+    def combine_meta(hash)
+      meta = {}
+      TagRegistry.signatures.each do |s|
+        name = s[:tagname]
+        meta[name] = hash[name] if hash[name]
+      end
+      meta
+    end
+
     # Some alias types are shown differently.
     # e.g. instead of "widget:" we show "xtype:"
     def alias_display_name(key)

data/lib/jsduck/source/file.rb

@@ -1,4 +1,3 @@
-require 'jsduck/source/file_parser'
 require 'jsduck/util/html'
 
 module JsDuck
@@ -14,16 +13,15 @@ module JsDuck
       attr_reader :docs
       attr_reader :html_filename
 
-      def initialize(contents, filename="", options={})
+      def initialize(contents, docs, filename="")
         @contents = contents
+        @docs = docs
         @filename = filename
         @html_filename = ""
         @links = {}
 
-        @docs = Source::FileParser.new.parse(@contents, @filename, options)
-
         @docs.map do |docset|
-          link(docset[:linenr], docset)
+          link(docset)
         end
       end
 
@@ -76,20 +74,13 @@ module JsDuck
       private
 
       # Creates two-way link between sourcefile and doc-object.
-      # If doc-object is class, links also the contained cfgs and constructor.
       # Returns the modified doc-object after done.
-      def link(linenr, doc)
+      def link(docset)
+        file = docset[:files].first
+        linenr = file[:linenr]
         @links[linenr] = [] unless @links[linenr]
-        file = {
-          :filename => @filename,
-          :linenr => linenr,
-        }
-        @links[linenr] << {:doc => doc, :file => file}
-        doc[:files] = [file]
-        if doc[:tagname] == :class
-          doc[:members].each {|m| link(linenr, m) }
-        end
-        doc
+        @links[linenr] << {:doc => docset, :file => file}
+        docset
       end
 
     end

data/lib/jsduck/tag/abstract.rb

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

data/lib/jsduck/tag/accessor.rb

@@ -0,0 +1,10 @@
+require "jsduck/tag/boolean_tag"
+
+module JsDuck::Tag
+  class Accessor < BooleanTag
+    def initialize
+      @pattern = "accessor"
+      super
+    end
+  end
+end

data/lib/jsduck/tag/alias.rb

@@ -0,0 +1,61 @@
+require "jsduck/tag/inheritdoc"
+require "jsduck/js/utils"
+
+module JsDuck::Tag
+  class Alias < Inheritdoc
+    def initialize
+      @pattern = "alias"
+      @tagname = :aliases
+      @ext_define_pattern = "alias"
+      @ext_define_default = {:aliases => []}
+      @merge_context = :class
+    end
+
+    # For backwards compatibility decide whether the @alias was used
+    # as @inheritdoc (@alias used to have the meaning of @inheritdoc
+    # before) or as a real Ext4 style alias definition.
+    def parse_doc(p)
+      if p.look(/([\w.]+)?#\w+/)
+        parse_as_inheritdoc(p)
+      else
+        parse_as_alias(p)
+      end
+    end
+
+    # @alias widget.foo
+    def parse_as_alias(p)
+      {
+        :tagname => :aliases,
+        :name => p.ident_chain,
+      }
+    end
+
+    def process_doc(h, tags, pos)
+      h[:aliases] = tags.map {|tag| tag[:name] }
+    end
+
+    def parse_ext_define(cls, ast)
+      cls[:aliases] += JsDuck::Js::Utils.make_string_list(ast)
+    end
+
+    def merge(h, docs, code)
+      h[:aliases] = build_aliases_hash(docs[:aliases] || code[:aliases] || [])
+    end
+
+    # Given array of full alias names like "foo.bar", "foo.baz"
+    # build hash like {"foo" => ["bar", "baz"]}
+    def build_aliases_hash(aliases)
+      hash={}
+      aliases.each do |a|
+        if a =~ /^([^.]+)\.(.+)$/
+          if hash[$1]
+            hash[$1] << $2
+          else
+            hash[$1] = [$2]
+          end
+        end
+      end
+      hash
+    end
+  end
+end

data/lib/jsduck/tag/alternate_class_names.rb

@@ -0,0 +1,17 @@
+require "jsduck/tag/class_list_tag"
+
+module JsDuck::Tag
+  class AlternateClassNames < ClassListTag
+    def initialize
+      @pattern = ["alternateClassName", "alternateClassNames"]
+      @tagname = :alternateClassNames
+      @ext_define_pattern = "alternateClassName"
+      @ext_define_default = {:alternateClassNames => []}
+      @merge_context = :class
+    end
+
+    def merge(h, docs, code)
+      h[@tagname] = docs[@tagname] || code[@tagname] || []
+    end
+  end
+end

data/lib/jsduck/tag/aside.rb

@@ -1,38 +1,33 @@
-require "jsduck/meta_tag"
+require "jsduck/tag/tag"
 require "jsduck/logger"
 
 module JsDuck::Tag
-  # Implementation of @aside tag.
-  class Aside < JsDuck::MetaTag
+  class Aside < Tag
     def initialize
-      @name = "aside"
-      @key = :aside
-      @position = :top
-      @allowed_types = {
-        :guide => true,
-        :video => true,
-        :example => true,
+      @pattern = "aside"
+      @tagname = :aside
+      @html_position = POS_ASIDE
+    end
+
+    # Parses: @aside [ guide | video| example ] name
+    def parse_doc(p)
+      {
+        :tagname => :aside,
+        :type => aside_type(p),
+        :name => p.hw.ident,
       }
     end
 
-    def to_value(asides)
-      asides.map do |line|
-        if line =~ /\A(\w+) +([^ ].*)\Z/
-          type = $1.to_sym
-          name = $2.strip
-          if @allowed_types[type]
-            {:type => type, :name => name}
-          else
-            warn("Unknown @aside type: #{type}")
-          end
-        else
-          warn("Bad syntax: @aside #{line}")
-        end
-      end.compact
+    def aside_type(p)
+      p.look(/\w+/) ? p.ident.to_sym : nil
     end
 
-    def to_html(asides)
-      asides.map do |aside|
+    def process_doc(h, tags, pos)
+      h[:aside] = tags
+    end
+
+    def to_html(context)
+      context[:aside].map do |aside|
         type = aside[:type]
         name = aside[:name]
         assets_group = get_assets_group(type)
@@ -49,11 +44,14 @@ module JsDuck::Tag
             </div>
           EOHTML
         else
-          warn("Unknown @aside name: #{type} #{name}")
+          warn("Unknown @aside name: #{type} #{name}", context)
         end
       end.compact
     end
 
+    # special accessor for @aside alone through which assets are set
+    attr_accessor :assets
+
     def get_assets_group(type)
       case type
       when :guide then @assets.guides
@@ -63,12 +61,11 @@ module JsDuck::Tag
       end
     end
 
-    def warn(msg)
-      ctx = @context ? @context[:files][0] : {}
-      JsDuck::Logger.warn(:aside, msg, ctx[:filename], ctx[:linenr])
+    def warn(msg, context)
+      file = context[:files][0]
+      JsDuck::Logger.warn(:aside, msg, file[:filename], file[:linenr])
       nil
     end
 
   end
 end
-