solvas-jsduck 6.0.0.beta.1888

data/lib/jsduck/tag/since.rb

@@ -0,0 +1,30 @@
+require "jsduck/tag/tag"
+require 'jsduck/util/html'
+
+module JsDuck::Tag
+  class Since < Tag
+    def initialize
+      @pattern = "since"
+      @tagname = :since
+      @html_position = POS_SINCE
+    end
+
+    def parse_doc(p, pos)
+      {
+        :tagname => :since,
+        :version => p.match(/.*$/).strip,
+      }
+    end
+
+    def process_doc(h, tags, pos)
+      h[:since] = tags[0][:version]
+    end
+
+    def to_html(context)
+      <<-EOHTML
+        <p>Available since: <b>#{JsDuck::Util::HTML.escape(context[:since])}</b></p>
+      EOHTML
+    end
+
+  end
+end

data/lib/jsduck/tag/singleton.rb

@@ -0,0 +1,28 @@
+require "jsduck/tag/boolean_tag"
+
+module JsDuck::Tag
+  class Singleton < BooleanTag
+    def initialize
+      @pattern = "singleton"
+      @ext_define_pattern = "singleton"
+      @class_icon = {
+        :small => File.dirname(__FILE__) + "/icons/singleton.png",
+        :large => File.dirname(__FILE__) + "/icons/singleton-large.png",
+        :redirect => File.dirname(__FILE__) + "/icons/singleton-redirect.png",
+        :priority => PRIORITY_SINGLETON,
+      }
+      @signature = {:long => "singleton", :short => "single"}
+      @css = <<-EOCSS
+        .signature .singleton {
+          background-color: transparent;
+          color: #929292;
+        }
+      EOCSS
+      super
+    end
+
+    def parse_ext_define(cls, ast)
+      cls[:singleton] = (ast.to_value == true)
+    end
+  end
+end

data/lib/jsduck/tag/static.rb

@@ -0,0 +1,12 @@
+require "jsduck/tag/boolean_tag"
+
+module JsDuck::Tag
+  class Static < BooleanTag
+    def initialize
+      @pattern = "static"
+      @signature = {:long => "static", :short => "STA"}
+      @css = ".signature .static { background-color: #484848 }" # Docs text color
+      super
+    end
+  end
+end

data/lib/jsduck/tag/subproperties.rb

@@ -0,0 +1,23 @@
+require "jsduck/tag/tag"
+require "jsduck/render/subproperties"
+
+module JsDuck::Tag
+  # There is no @subproperties tag.
+  #
+  # This tag class exists solely to implement rendering of :properties
+  # field which can exist in :cfg, :property or :css_var members.
+  class Subproperties < Tag
+    def initialize
+      @tagname = :properties
+      @html_position = POS_SUBPROPERTIES
+    end
+
+    def format(m, formatter)
+      m[:properties].each {|p| formatter.format_subproperty(p) }
+    end
+
+    def to_html(m)
+      JsDuck::Render::Subproperties.render(m)
+    end
+  end
+end

data/lib/jsduck/tag/tag.rb

@@ -0,0 +1,164 @@
+module JsDuck::Tag
+  # Base class for all builtin tags.
+  class Tag
+    # Defines the name of the @tag.
+    # The name itself must not contain the "@" sign.
+    # 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.
+    #
+    # Can return a hash or array of hashes representing the detected
+    # @tag data.  Each returned hash must contain the :tagname key,
+    # e.g.:
+    #
+    #     {:tagname => :protected, :foo => "blah"}
+    #
+    # All hashes with the same :tagname will later be combined
+    # together and passed on to #process_doc method of this Tag class
+    # that has @tagname field set to that tagname.
+    #
+    # The hash can also contain :doc => :multiline, in which case all
+    # the documentation following this tag will get added to the :doc
+    # field of the tag and will later be accessible in #process_doc
+    # method.
+    #
+    # 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
+    # member/class hash.
+    attr_reader :tagname
+
+    # Gets called with the resulting class/member hash and array of
+    # @tag data that was generated by #parse_doc. Also a hash with
+    # position information {:filename, :linenr} is passed in.
+    #
+    # It can then add a new field to the class/member hash or
+    # transform it in any other way desired.
+    def process_doc(hash, docs, position)
+    end
+
+    # The text to display in member signature.  Must be a hash
+    # defining the short and long versions of the signature text:
+    #
+    #     {:long => "something", :short => "SOM"}
+    #
+    # Additionally the hash can contain a :tooltip which is the text
+    # to be shown when the signature bubble is hovered over in docs.
+    attr_reader :signature
+
+    # Defines the name of object property in Ext.define()
+    # configuration which, when encountered, will cause the
+    # #parse_ext_define method to be invoked.
+    attr_reader :ext_define_pattern
+
+    # The default value to use when Ext.define is encountered, but the
+    # key in the config object itself is not found.
+    # This must be a Hash defining the key and value.
+    attr_reader :ext_define_default
+
+    # Called by Ast class to parse a config in Ext.define().
+    # @param {Hash} cls A simple Hash representing a class on which
+    # various properties can be set.
+    # @param {AstNode} ast Value of the config in Ext.define().
+    def parse_ext_define(cls, ast)
+    end
+
+    # The position for outputting the HTML for the tag in final
+    # documentation.
+    #
+    # Must be defined together with #to_html method.  Additionally the
+    # #format method can be defined to perform rendering of Markdown
+    # before #to_html is called.
+    #
+    # All builtin tags have a position that's defined by one of the
+    # constants listed below.  For user-defined tags it's recommended
+    # to define your position relative to one of the builtin tags.
+    # For example if you want your tag to output HTML right after the
+    # return value documentation, use something like:
+    #
+    #     @html_position = POS_RETURN + 0.1
+    #
+    # Later versions of JSDuck might change the actual values of these
+    # constants, so don't rely on the concrete values, reference the
+    # constants and add/substract fractions smaller than 1 from them.
+    #
+    attr_accessor :html_position
+
+    POS_ASIDE = 1
+    POS_PRIVATE = 2
+    POS_DOC = 3
+    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_FIRES = 15
+    POS_OVERRIDES = 16
+
+    # Called before #to_html to allow rendering of Markdown content.
+    # For this an instance of DocFormatter is passed in, on which one
+    # can call the #format method to turn Markdown into HTML.
+    def format(context, formatter)
+    end
+
+    # Implement #to_html to transform tag data to HTML to be included
+    # into documentation.
+    #
+    # It gets passed the full class/member hash. It should return an
+    # HTML string to inject into document.
+    #
+    def to_html(context)
+    end
+
+    # A string of CSS to add to the builtin CSS of the generated docs.
+    # For example, to style a signature label:
+    #
+    #     @css = ".signature .mytag { color: red }"
+    #
+    attr_reader :css
+
+    # Defines custom class icon files.
+    #
+    # It must be a hash with the following keys:
+    #
+    # - :large - the large icon used in class header
+    # - :small - small icon used in class tree and search
+    # - :redirect - redirect icon for alternateClassNames in search.
+    # - :priority - a number to determine which icon gets used when
+    #      a class has several tags that set a custom icon.  An icon
+    #      with a larger priority wins.
+    #
+    # Used by @class tag to define the default icon.
+    # Used by @singleton and @component tags for a different icon.
+    attr_reader :class_icon
+
+    PRIORITY_SINGLETON = 2
+    PRIORITY_COMPONENT = 1
+    PRIORITY_CLASS = 0
+
+    # Returns all descendants of JsDuck::Tag::Tag class.
+    def self.descendants
+      result = []
+      ObjectSpace.each_object(::Class) do |cls|
+        result << cls if cls < self
+      end
+      result
+    end
+  end
+end

data/lib/jsduck/tag/template.rb

@@ -0,0 +1,29 @@
+require "jsduck/tag/boolean_tag"
+
+module JsDuck::Tag
+  class Template < BooleanTag
+    def initialize
+      @pattern = "template"
+      @signature = {:long => "template", :short => "TMP"}
+      @html_position = POS_TEMPLATE
+      # Box with light gray background
+      @css = <<-EOCSS
+        .template-box {
+          text-align: center;
+          background-color: #eee;
+        }
+      EOCSS
+      super
+    end
+
+    def to_html(context)
+      <<-EOHTML
+      <div class='rounded-box template-box'>
+      <p>This is a <a href="#!/guide/components">template method</a>.
+         a hook into the functionality of this class.
+         Feel free to override it in child classes.</p>
+      </div>
+      EOHTML
+    end
+  end
+end

data/lib/jsduck/tag/throws.rb

@@ -0,0 +1,39 @@
+require "jsduck/tag/tag"
+require "jsduck/render/subproperties"
+
+module JsDuck::Tag
+  class Throws < Tag
+    def initialize
+      @pattern = "throws"
+      @tagname = :throws
+      @repeatable = true
+      @html_position = POS_THROWS
+    end
+
+    # @throws {Type} ...
+    def parse_doc(p, pos)
+      tag = p.standard_tag({:tagname => :throws, :type => true})
+      tag[:doc] = :multiline
+      tag
+    end
+
+    def process_doc(h, tags, pos)
+      result = tags.map do |throws|
+        {
+          :type => throws[:type] || "Object",
+          :doc => throws[:doc] || "",
+        }
+      end
+
+      h[:throws] = result
+    end
+
+    def format(m, formatter)
+      m[:throws].each {|t| formatter.format_subproperty(t) }
+    end
+
+    def to_html(m)
+      JsDuck::Render::Subproperties.render_throws(m[:throws])
+    end
+  end
+end

data/lib/jsduck/tag/type.rb

@@ -0,0 +1,38 @@
+require "jsduck/tag/tag"
+
+module JsDuck::Tag
+  class Type < Tag
+    def initialize
+      @pattern = "type"
+      @tagname = :type
+
+      # We don't really care about the position as we don't output any
+      # HTML. We just need to set this up to do the formatting.
+      @html_position = POS_DOC
+    end
+
+    # matches @type {type}  or  @type type
+    #
+    # 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, pos)
+      tag = p.standard_tag({:tagname => :type, :type => true, :optional => true})
+      tag[:type] = curlyless_type(p) unless tag[:type]
+      tag
+    end
+
+    def curlyless_type(p)
+      p.match(/\S+/)
+    end
+
+    def process_doc(h, tags, pos)
+      h[:type] = tags[0][:type] unless h[:type]
+    end
+
+    def format(m, formatter)
+      m[:html_type] = formatter.format_type(m[:type])
+    end
+
+  end
+end

data/lib/jsduck/tag/uses.rb

@@ -0,0 +1,13 @@
+require "jsduck/tag/class_list_tag"
+
+module JsDuck::Tag
+  class Uses < ClassListTag
+    def initialize
+      @pattern = "uses"
+      @tagname = :uses
+      @repeatable = true
+      @ext_define_pattern = "uses"
+      @ext_define_default = {:uses => []}
+    end
+  end
+end

data/lib/jsduck/tag/xtype.rb

@@ -0,0 +1,31 @@
+require "jsduck/tag/tag"
+require "jsduck/js/utils"
+
+module JsDuck::Tag
+  class Xtype < Tag
+    def initialize
+      @pattern = "xtype"
+      @ext_define_pattern = "xtype"
+      @repeatable = true
+    end
+
+    # @xtype name
+    def parse_doc(p, pos)
+      {
+        :tagname => :aliases,
+        :name => parse_alias_shorthand(p, "widget")
+      }
+    end
+
+    # Parses the name after @ftype, @xtype or @ptype
+    # and returns it with the given namespace prefix.
+    def parse_alias_shorthand(p, namespace)
+      namespace + "." + (p.ident_chain || "")
+    end
+
+    def parse_ext_define(cls, ast)
+      cls[:aliases] += JsDuck::Js::Utils.make_string_list(ast).map {|xtype| "widget."+xtype }
+    end
+
+  end
+end

data/lib/jsduck/tag_loader.rb

@@ -0,0 +1,50 @@
+require "jsduck/tag/tag"
+
+module JsDuck
+
+  # Loads Tag classes from the builtin tags/ dir and optionally also
+  # from additional paths.
+  class TagLoader
+    def initialize(extra_paths=[])
+      @paths = [File.dirname(__FILE__) + "/tag"]
+      @paths += extra_paths
+    end
+
+    # Loads Tag classes from all supplied paths.
+    #
+    # Returns the tag classes that got loaded, sorted alphabetically
+    # 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 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
+    end
+
+    def tag_classes
+      classes = JsDuck::Tag::Tag.descendants
+      # 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
+
+  end
+
+end