jsduck 4.10.4 → 5.0.0.beta01

data/lib/jsduck/tag/requires.rb

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

data/lib/jsduck/tag/return.rb

@@ -0,0 +1,47 @@
+require "jsduck/tag/tag"
+require "jsduck/doc/subproperties"
+require "jsduck/render/subproperties"
+
+module JsDuck::Tag
+  class Return < Tag
+    def initialize
+      @pattern = ["return", "returns"]
+      @tagname = :return
+      @html_position = POS_RETURN
+    end
+
+    # @return {Type} return.name ...
+    def parse_doc(p)
+      tag = p.standard_tag({:tagname => :return, :type => true})
+      tag[:name] = subproperty_name(p)
+      tag[:doc] = :multiline
+      tag
+    end
+
+    def subproperty_name(p)
+      if p.hw.look(/return\.\w/)
+        p.ident_chain
+      else
+        "return"
+      end
+    end
+
+    def process_doc(h, tags, pos)
+      ret = tags[0]
+      h[:return] = {
+        :type => ret[:type] || "Object",
+        :name => ret[:name] || "return",
+        :doc => ret[:doc] || "",
+        :properties => JsDuck::Doc::Subproperties.nest(tags, pos)[0][:properties],
+      }
+    end
+
+    def format(m, formatter)
+      formatter.format_subproperty(m[:return])
+    end
+
+    def to_html(m)
+      JsDuck::Render::Subproperties.render_return(m[:return])
+    end
+  end
+end

data/lib/jsduck/tag/since.rb

@@ -1,26 +1,34 @@
-require "jsduck/meta_tag"
+require "jsduck/tag/tag"
 require "jsduck/logger"
 
 module JsDuck::Tag
-  # Implementation of @since tag.
-  class Since < JsDuck::MetaTag
+  class Since < Tag
     def initialize
-      @name = "since"
-      @key = :since
+      @pattern = "since"
+      @tagname = :since
+      @html_position = POS_SINCE
     end
 
-    def to_value(contents)
-      if contents.length > 1
+    def parse_doc(p)
+      {
+        :tagname => :since,
+        :version => p.match(/.*$/).strip,
+      }
+    end
+
+    def process_doc(h, tags, pos)
+      if tags.length > 1
         JsDuck::Logger.warn(nil, "Only one @since tag allowed per class/member.")
       end
-      contents[0]
+
+      h[:since] = tags[0][:version]
     end
 
-    def to_html(version)
+    def to_html(context)
       <<-EOHTML
-        <p>Available since: <b>#{version}</b></p>
+        <p>Available since: <b>#{context[:since]}</b></p>
       EOHTML
     end
+
   end
 end
-

data/lib/jsduck/tag/singleton.rb

@@ -0,0 +1,15 @@
+require "jsduck/tag/boolean_tag"
+
+module JsDuck::Tag
+  class Singleton < BooleanTag
+    def initialize
+      @pattern = "singleton"
+      @ext_define_pattern = "singleton"
+      super
+    end
+
+    def parse_ext_define(cls, ast)
+      cls[:singleton] = (ast.to_value == true)
+    end
+  end
+end

data/lib/jsduck/tag/static.rb

@@ -1,14 +1,12 @@
-require "jsduck/meta_tag"
+require "jsduck/tag/boolean_tag"
 
 module JsDuck::Tag
-  # Implementation of @static tag
-  class Static < JsDuck::MetaTag
+  class Static < BooleanTag
     def initialize
-      @name = "static"
-      @key = :static
+      @pattern = "static"
       @signature = {:long => "static", :short => "STA"}
-      @boolean = true
+      @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,208 @@
+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
+
+    # 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.
+    def parse_doc(p)
+    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
+
+    # Defines a class member type and specifies a name and several
+    # other settings.  For example:
+    #
+    #     {
+    #       :name => :event,
+    #       :category => :method_like,
+    #       :title => "Events",
+    #       :position => MEMBER_POS_EVENT,
+    #       # The following are optional
+    #       :toolbar_title => "Events",
+    #       :subsections => [
+    #         {:title => "Static events",
+    #          :filter => {:static => false},
+    #          :default => true},
+    #         {:title => "Instance events",
+    #          :filter => {:static => true}},
+    #       ]
+    #     }
+    #
+    # The category must be either :property_like or :method_like.
+    #
+    # Position defines the ordering of member section in final HTML
+    # output.
+    #
+    # Title is shown at the top of each such section and also as a
+    # label on Docs app toolbar button unless :toolbar_title is
+    # specified.
+    #
+    # Subsections allows splitting the list of members to several
+    # subgroups.  For example methods get split into static and
+    # instance methods.
+    #
+    # - The :filter field defines how to filter out the members for
+    #   this subcategory.  :static=>true filters out all members that
+    #   have a :static field with a truthy value.  Conversely,
+    #   :static=>false filters out members not having a :static field
+    #   or having it with a falsy value.
+    #
+    # - Setting :default=>true will hide the subsection title when all
+    #   the members end up in that subsection.  For example when there
+    #   are only instance methods, the docs will only contain the
+    #   section title "Methods", as by default one should assume all
+    #   methods are instance methods if not stated otherwise.
+    #
+    attr_reader :member_type
+
+    MEMBER_POS_CFG = 1
+    MEMBER_POS_PROPERTY = 2
+    MEMBER_POS_METHOD = 3
+    MEMBER_POS_EVENT = 4
+    MEMBER_POS_CSS_VAR = 5
+    MEMBER_POS_CSS_MIXIN = 6
+
+    # 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
+
+    # In the context of which members or classes invoke the #merge
+    # method.  This can be either a single tagname like :class,
+    # :method, :cfg or an array of these.
+    #
+    # Additionally a few special symbols can be used to register a
+    # merger for a set of member types:
+    #
+    #   - :member - all members.
+    #   - :method_like - members like :method, :event, :css_mixin
+    #   - :property_like - members like :cfg, :property, :css_var
+    #
+    # For example to register a merger for everyting:
+    #
+    #     @merge_context = [:class, :member]
+    #
+    attr_reader :merge_context
+
+    # Merges documentation and code hashes into the result hash.
+    def merge(hash, docs, code)
+    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_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
+
+    # 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
+
+    # 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

@@ -1,18 +1,24 @@
-require "jsduck/meta_tag"
+require "jsduck/tag/boolean_tag"
 
 module JsDuck::Tag
-  # Implementation of @template tag
-  class Template < JsDuck::MetaTag
+  class Template < BooleanTag
     def initialize
-      @name = "template"
-      @key = :template
+      @pattern = "template"
       @signature = {:long => "template", :short => "TMP"}
-      @boolean = true
+      @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(contents)
+    def to_html(context)
       <<-EOHTML
-      <div class='signature-box template'>
+      <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>
@@ -21,4 +27,3 @@ module JsDuck::Tag
     end
   end
 end
-

data/lib/jsduck/tag/throws.rb

@@ -0,0 +1,38 @@
+require "jsduck/tag/tag"
+require "jsduck/render/subproperties"
+
+module JsDuck::Tag
+  class Throws < Tag
+    def initialize
+      @pattern = "throws"
+      @tagname = :throws
+      @html_position = POS_THROWS
+    end
+
+    # @throws {Type} ...
+    def parse_doc(p)
+      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