solvas-jsduck 6.0.0.beta.1888

data/lib/jsduck/tag/default.rb

@@ -0,0 +1,25 @@
+require "jsduck/tag/tag"
+require "jsduck/util/html"
+
+module JsDuck::Tag
+  # There is no @default tag.
+  #
+  # Default values are detected from syntax like this:
+  #
+  #     @cfg [blah=somedefault]
+  #
+  # This tag class exists to generate the "Defaults to:" text in final
+  # HTML.
+  class Default < Tag
+    def initialize
+      @tagname = :default
+      @html_position = POS_DEFAULT
+    end
+
+    def to_html(m)
+      return if m[:default] == "undefined"
+
+      "<p>Defaults to: <code>" + JsDuck::Util::HTML.escape(m[:default]) + "</code></p>"
+    end
+  end
+end

data/lib/jsduck/tag/deprecated.rb

@@ -0,0 +1,23 @@
+require "jsduck/tag/deprecated_tag"
+
+module JsDuck::Tag
+  class Deprecated < DeprecatedTag
+    def initialize
+      @tagname = :deprecated
+      @msg = "This {TAGNAME} has been <strong>deprecated</strong>"
+      @css = <<-EOCSS
+        .signature .deprecated {
+          background-color: #aa0000;
+        }
+        .deprecated-box {
+          border: 2px solid #aa0000;
+        }
+        .deprecated-box strong {
+          color: white;
+          background-color: #aa0000;
+        }
+      EOCSS
+      super
+    end
+  end
+end

data/lib/jsduck/tag/deprecated_tag.rb

@@ -0,0 +1,60 @@
+require "jsduck/tag/tag"
+
+module JsDuck::Tag
+  # Base class for both @deprecated and @removed.  Child classes only
+  # need to define the @tagname and @msg attributes and call #super -
+  # all the correct behavior will the fall out automatically.
+  class DeprecatedTag < Tag
+    def initialize
+      if @tagname
+        @pattern = @tagname.to_s
+        @signature = {:long => @tagname.to_s, :short => @tagname.to_s[0..2].upcase}
+        @html_position = POS_DEPRECATED
+        @since = "since" unless @since
+        @css += <<-EOCSS
+          .deprecated-tag-box {
+            text-align: center;
+            color: #600;
+            background-color: #fee;
+          }
+          .deprecated-tag-box strong {
+            text-transform: uppercase;
+            border-radius: 2px;
+            padding: 0 3px;
+          }
+        EOCSS
+      end
+    end
+
+    def parse_doc(p, pos)
+      {
+        :tagname => @tagname,
+        :version => p.match(/[0-9.]+/),
+        :doc => :multiline,
+      }
+    end
+
+    def process_doc(h, tags, pos)
+      v = {:text => tags[0][:doc] || ""}
+      v[:version] = tags[0][:version] if tags[0][:version]
+      h[@tagname] = v
+    end
+
+    def format(context, formatter)
+      context[@tagname][:text] = formatter.format(context[@tagname][:text])
+    end
+
+    def to_html(context)
+      depr = context[@tagname]
+      msg = @msg.sub(/\{TAGNAME\}/, context[:tagname].to_s)
+      v = depr[:version] ? "#{@since} " + depr[:version] : ""
+      <<-EOHTML
+        <div class='rounded-box #{@tagname}-box deprecated-tag-box'>
+        <p>#{msg} #{v}</p>
+        #{depr[:text]}
+        </div>
+      EOHTML
+    end
+
+  end
+end

data/lib/jsduck/tag/doc.rb

@@ -0,0 +1,32 @@
+require "jsduck/tag/tag"
+require 'jsduck/format/shortener'
+
+module JsDuck::Tag
+  # A special class for rendering the documentation field inside
+  # classes and members.
+  class Doc < Tag
+    def initialize
+      @tagname = :doc
+      @html_position = POS_DOC
+      @shortener = JsDuck::Format::Shortener.new
+    end
+
+    def format(m, formatter)
+      m[:doc] = formatter.format(m[:doc])
+
+      if expandable?(m) || @shortener.too_long?(m[:doc])
+        m[:short_doc] = @shortener.shorten(m[:doc])
+      end
+    end
+
+    def to_html(m)
+      m[:doc]
+    end
+
+    private
+
+    def expandable?(m)
+      m[:params] || (m[:properties] && m[:properties].length > 0) || m[:default] || m[:deprecated] || m[:template]
+    end
+  end
+end

data/lib/jsduck/tag/docauthor.rb

@@ -0,0 +1,12 @@
+require "jsduck/tag/author"
+
+module JsDuck::Tag
+  # Exactly the same as @author tag - it's simply ignored.
+  class Docauthor < Author
+    def initialize
+      super
+      @pattern = "docauthor"
+      @tagname = :docauthor
+    end
+  end
+end

data/lib/jsduck/tag/enum.rb

@@ -0,0 +1,67 @@
+require "jsduck/tag/tag"
+
+module JsDuck::Tag
+  class Enum < Tag
+    def initialize
+      @pattern = "enum"
+      @tagname = :enum
+      @html_position = POS_ENUM
+      # Green box
+      @css = <<-EOCSS
+        .enum-box {
+          color: #060;
+          background-color: #efe;
+          text-align: center;
+        }
+      EOCSS
+    end
+
+    # @enum {Type} [name=default] ...
+    def parse_doc(p, pos)
+      enum = p.standard_tag({
+          :tagname => :enum,
+          :type => true,
+          :name => true,
+          :default => true,
+          :optional => true
+        })
+
+      # @enum is a special case of class, so we also generate a class
+      # tag with the same name as given for @enum.
+      cls = {:tagname => :class, :name => enum[:name]}
+
+      return [cls, enum]
+    end
+
+    def process_doc(h, tags, pos)
+      h[:enum] = {
+        :type => tags[0][:type],
+        :default => tags[0][:default],
+        :doc_only => !!tags[0][:default],
+      }
+    end
+
+    def to_html(cls)
+      if cls[:enum][:doc_only]
+        first = cls[:members][0] || {:name => 'foo', :default => '"foo"'}
+        [
+          "<div class='rounded-box enum-box'>",
+          "<p><strong>ENUM:</strong> ",
+          "This enumeration defines a set of String values. ",
+          "It exists primarily for documentation purposes - ",
+          "in code use the actual string values like #{first[:default]}, ",
+          "don't reference them through this class like #{cls[:name]}.#{first[:name]}.</p>",
+          "</div>",
+        ]
+      else
+        [
+          "<div class='rounded-box enum-box'>",
+          "<p><strong>ENUM:</strong> ",
+          "This enumeration defines a set of #{cls[:enum][:type]} values.</p>",
+          "</div>",
+        ]
+      end
+    end
+
+  end
+end

data/lib/jsduck/tag/event.rb

@@ -0,0 +1,36 @@
+require "jsduck/tag/member_tag"
+require "jsduck/params_merger"
+
+module JsDuck::Tag
+  class Event < MemberTag
+    def initialize
+      @pattern = "event"
+      @tagname = :event
+      @member_type = {
+        :title => "Events",
+        :position => MEMBER_POS_EVENT,
+        :icon => File.dirname(__FILE__) + "/icons/event.png"
+      }
+    end
+
+    # @event name ...
+    def parse_doc(p, pos)
+      {
+        :tagname => :event,
+        :name => p.ident,
+      }
+    end
+
+    def process_doc(h, tags, pos)
+      h[:name] = tags[0][:name]
+    end
+
+    def merge(h, docs, code)
+      JsDuck::ParamsMerger.merge(h, docs, code)
+    end
+
+    def to_html(event, cls)
+      member_link(event) + member_params(event[:params])
+    end
+  end
+end

data/lib/jsduck/tag/evented.rb

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

data/lib/jsduck/tag/experimental.rb

@@ -0,0 +1,28 @@
+require "jsduck/tag/deprecated_tag"
+
+module JsDuck::Tag
+  class Experimental < DeprecatedTag
+    def initialize
+      @tagname = :experimental
+      @msg = "This {TAGNAME} is <strong>experimental</strong>"
+      @since = "Introduced in"
+      # dashed border
+      @css = <<-EOCSS
+        .signature .experimental {
+          color: #a00;
+          border: 1px dashed #a00;
+          background-color: #fee;
+        }
+        .experimental-box {
+          border: 2px dashed #ccc;
+        }
+        .experimental-box strong {
+          margin: 0 3px;
+          border: 2px dashed #a00;
+          color: #a00;
+        }
+      EOCSS
+      super
+    end
+  end
+end

data/lib/jsduck/tag/extends.rb

@@ -0,0 +1,39 @@
+require "jsduck/tag/tag"
+require "jsduck/js/utils"
+
+module JsDuck::Tag
+  class Extends < Tag
+    def initialize
+      @pattern = ["extend", "extends"]
+      @tagname = :extends
+      @ext_define_pattern = "extend"
+      @ext_define_default = {:extends => "Ext.Base"}
+    end
+
+    # @extends classname
+    # or
+    # @extends {classname}
+    def parse_doc(p, pos)
+      if p.match(/\{/)
+        cls = p.ident_chain
+        p.match(/\}/)
+      else
+        cls = p.ident_chain
+      end
+
+      {
+        :tagname => :extends,
+        :extends => cls,
+      }
+    end
+
+    def process_doc(h, tags, pos)
+      h[:extends] = tags[0][:extends]
+    end
+
+    def parse_ext_define(cls, ast)
+      cls[:extends] = JsDuck::Js::Utils.make_string(ast)
+    end
+
+  end
+end

data/lib/jsduck/tag/fires.rb

@@ -0,0 +1,55 @@
+require "jsduck/tag/tag"
+require "jsduck/logger"
+
+module JsDuck::Tag
+  class Fires < Tag
+    def initialize
+      @pattern = "fires"
+      @tagname = :fires
+      @repeatable = true
+      @html_position = POS_FIRES
+    end
+
+    # @fires eventname
+    def parse_doc(p, pos)
+      {:tagname => :fires, :events => ident_list(p)}
+    end
+
+    # matches <ident> <ident> ... until line end
+    def ident_list(p)
+      list = []
+      while ident = p.hw.ident
+        list << ident
+      end
+      list
+    end
+
+    def process_doc(h, tags, pos)
+      h[:fires] = tags.map {|t| t[:events] }.flatten
+    end
+
+    def format(m, formatter)
+      cls = formatter.relations[m[:owner]]
+
+      m[:fires] = m[:fires].map do |name|
+        if cls.find_members({:tagname => :event, :name => name}).length > 0
+          formatter.link(m[:owner], name, name, :event)
+        else
+          JsDuck::Logger.warn(:fires, "@fires references unknown event: #{name}", m[:files][0])
+          name
+        end
+      end
+    end
+
+    def to_html(m)
+      return unless m[:fires] && m[:fires].length > 0
+
+      return [
+        "<h3 class='pa'>Fires</h3>",
+        "<ul>",
+          m[:fires].map {|e| "<li>#{e}</li>" },
+        "</ul>",
+      ]
+    end
+  end
+end

data/lib/jsduck/tag/ftype.rb

@@ -0,0 +1,19 @@
+require "jsduck/tag/xtype"
+
+module JsDuck::Tag
+  class Ftype < Xtype
+    def initialize
+      @pattern = "ftype"
+      @repeatable = true
+    end
+
+    # @ftype name
+    def parse_doc(p, pos)
+      {
+        :tagname => :aliases,
+        :name => parse_alias_shorthand(p, "feature")
+      }
+    end
+
+  end
+end

data/lib/jsduck/tag/hide.rb

@@ -0,0 +1,11 @@
+require "jsduck/tag/boolean_tag"
+
+module JsDuck::Tag
+  # Hides a member in parent class.
+  class Hide < BooleanTag
+    def initialize
+      @pattern = "hide"
+      super
+    end
+  end
+end