jsduck 4.10.4 → 5.0.0.beta01

data/lib/jsduck/tag/enum.rb

@@ -0,0 +1,70 @@
+require "jsduck/tag/tag"
+
+module JsDuck::Tag
+  class Enum < Tag
+    def initialize
+      @pattern = "enum"
+      @tagname = :enum
+      @merge_context = :class
+      @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)
+      enum = p.standard_tag({:tagname => :enum, :type => true, :name => 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
+
+    # Takes the :enum always from docs, but the :doc_only can come
+    # from either code or docs.
+    def merge(h, docs, code)
+      return unless docs[:enum]
+      h[:enum] = docs[:enum]
+      h[:enum][:doc_only] = docs[:enum][:doc_only] || (code[:enum] && code[:enum][:doc_only])
+    end
+
+    def to_html(cls)
+      if cls[:enum][:doc_only]
+        first = cls[:members][:property][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,28 @@
+require "jsduck/tag/tag"
+
+module JsDuck::Tag
+  class Event < Tag
+    def initialize
+      @pattern = "event"
+      @tagname = :event
+      @member_type = {
+        :name => :event,
+        :category => :method_like,
+        :title => "Events",
+        :position => MEMBER_POS_EVENT,
+      }
+    end
+
+    # @event name ...
+    def parse_doc(p)
+      {
+        :tagname => :event,
+        :name => p.ident,
+      }
+    end
+
+    def process_doc(h, tags, pos)
+      h[:name] = tags[0][:name]
+    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/extends.rb

@@ -0,0 +1,45 @@
+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"}
+      @merge_context = :class
+    end
+
+    # @extends classname
+    # or
+    # @extends {classname}
+    def parse_doc(p)
+      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
+
+    # Ignore extending of the Object class
+    def merge(h, docs, code)
+      h[:extends] = docs[:extends] || code[:extends]
+      h[:extends] = nil if h[:extends] == "Object"
+    end
+  end
+end

data/lib/jsduck/tag/ftype.rb

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

data/lib/jsduck/tag/hide.rb

@@ -1,18 +1,11 @@
-require "jsduck/meta_tag"
+require "jsduck/tag/boolean_tag"
 
 module JsDuck::Tag
-  # Implementation of @hide tag.
-  #
   # Hides a member in parent class.
-  #
-  # The core of the implementation is built into jsduck.
-  #
-  class Hide < JsDuck::MetaTag
+  class Hide < BooleanTag
     def initialize
-      @name = "hide"
-      @key = :hide
-      @boolean = true
+      @pattern = "hide"
+      super
     end
   end
 end
-

data/lib/jsduck/tag/ignore.rb

@@ -1,13 +1,12 @@
-require "jsduck/meta_tag"
+require "jsduck/tag/boolean_tag"
 
 module JsDuck::Tag
-  # @ignore is alias for @private
-  class Ignore < JsDuck::MetaTag
+  # Causes a member or entire class documentation to be completely
+  # excluded from docs.
+  class Ignore < BooleanTag
     def initialize
-      @name = "ignore"
-      @key = :ignore
-      @boolean = true
+      @pattern = "ignore"
+      super
     end
   end
 end
-

data/lib/jsduck/tag/inheritable.rb

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

data/lib/jsduck/tag/inheritdoc.rb

@@ -0,0 +1,48 @@
+require "jsduck/tag/tag"
+require "jsduck/tag_registry"
+
+module JsDuck::Tag
+  class Inheritdoc < Tag
+    def initialize
+      @pattern = ["inheritdoc", "inheritDoc"]
+      @tagname = :inheritdoc
+    end
+
+    # @inheritdoc class.name#static-type-member
+    def parse_doc(p)
+      parse_as_inheritdoc(p)
+    end
+
+    # This separate method exits to allow it to be also called from
+    # @alias tag implementation.
+    #
+    # Matches a member reference: <class.name> "#" <static> "-" <type> "-" <member>
+    #
+    # Returns :inheritdoc tag definition with corresponding fields.
+    def parse_as_inheritdoc(p)
+      tag = {
+        :tagname => :inheritdoc,
+        :cls => p.ident_chain,
+      }
+
+      if p.look(/#\w/)
+        p.match(/#/)
+        if p.look(/static-/)
+          tag[:static] = true
+          p.match(/static-/)
+        end
+        if p.look(JsDuck::TagRegistry.member_type_regex)
+          tag[:type] = p.match(/\w+/).to_sym
+          p.match(/-/)
+        end
+        tag[:member] = p.ident
+      end
+
+      tag
+    end
+
+    def process_doc(h, docs, pos)
+      h[:inheritdoc] = docs.first
+    end
+  end
+end

data/lib/jsduck/tag/markdown.rb

@@ -1,12 +1,14 @@
-require "jsduck/meta_tag"
+require "jsduck/tag/tag"
 
 module JsDuck::Tag
-  # A @markdown tag that is simply ignored
-  class Markdown < JsDuck::MetaTag
+  class Markdown < Tag
     def initialize
-      @name = "markdown"
-      @boolean = true
+      @pattern = "markdown"
+    end
+
+    # @markdown
+    def parse_doc(p)
+      # Just completely ignore this tag.
     end
   end
 end
-

data/lib/jsduck/tag/member.rb

@@ -0,0 +1,24 @@
+require "jsduck/tag/tag"
+
+module JsDuck::Tag
+  class Member < Tag
+    # This is an odd case where tag itself is @member, but the value
+    # of it gets stored in :owner.
+    def initialize
+      @pattern = "member"
+      @tagname = :owner
+    end
+
+    # @member classname
+    def parse_doc(p)
+      {
+        :tagname => :owner,
+        :owner => p.ident_chain,
+      }
+    end
+
+    def process_doc(h, tags, pos)
+      h[:owner] = tags[0][:owner]
+    end
+  end
+end

data/lib/jsduck/tag/method.rb

@@ -0,0 +1,35 @@
+require "jsduck/tag/tag"
+
+module JsDuck::Tag
+  # Implementation of @method tag.
+  class Method < Tag
+    def initialize
+      @pattern = "method"
+      @tagname = :method
+      @member_type = {
+        :name => :method,
+        :category => :method_like,
+        :title => "Methods",
+        :position => MEMBER_POS_METHOD,
+        :subsections => [
+          {:title => "Instance methods", :filter => {:static => false}, :default => true},
+          {:title => "Static methods", :filter => {:static => true}},
+        ]
+      }
+    end
+
+    # @method name ...
+    def parse_doc(p)
+      {
+        :tagname => :method,
+        :name => p.ident,
+      }
+    end
+
+    # Onle sets the name when it's actually specified.
+    # Otherwise we might overwrite name coming from @constructor.
+    def process_doc(h, tags, pos)
+      h[:name] = tags[0][:name] if tags[0][:name]
+    end
+  end
+end

data/lib/jsduck/tag/mixins.rb

@@ -0,0 +1,26 @@
+require "jsduck/tag/class_list_tag"
+
+module JsDuck::Tag
+  class Mixins < ClassListTag
+    def initialize
+      @pattern = ["mixin", "mixins"]
+      @tagname = :mixins
+      @ext_define_pattern = "mixins"
+      @ext_define_default = {:mixins => []}
+    end
+
+    # Override definition in parent class.  In addition to Array
+    # literal, mixins can be defined with an object literal.
+    def parse_ext_define(cls, ast)
+      cls[:mixins] = to_mixins_array(ast)
+    end
+
+    # converts AstNode, whether it's a string, array or hash into
+    # array of strings (when possible).
+    def to_mixins_array(ast)
+      v = ast.to_value
+      mixins = v.is_a?(Hash) ? v.values : Array(v)
+      mixins.all? {|mx| mx.is_a? String } ? mixins : []
+    end
+  end
+end

data/lib/jsduck/tag/name.rb

@@ -0,0 +1,36 @@
+require "jsduck/tag/tag"
+
+module JsDuck::Tag
+  # There is no @name tag.
+  #
+  # The :name field is generated by several tags like @class, @method,
+  # @cfg, ...
+  #
+  # This class exists to take care of the merging of :name field.
+  class Name < Tag
+    def initialize
+      @merge_context = [:class, :member]
+    end
+
+    # When docs contains :name, it's taken from there.
+    #
+    # When code contains :name, we only take the full name when
+    # dealing with a class, otherwise we just take the last part of
+    # the dot.separate.name.
+    #
+    # :name defaults to empty string.
+    def merge(h, docs, code)
+      if docs[:name]
+        h[:name] = docs[:name]
+      elsif code[:name]
+        if h[:tagname] == :class
+          h[:name] = code[:name]
+        else
+          h[:name] = code[:name].split(/\./).last
+        end
+      else
+        h[:name] = ""
+      end
+    end
+  end
+end

data/lib/jsduck/tag/new.rb

@@ -1,33 +1,19 @@
-require "jsduck/meta_tag"
-require "jsduck/logger"
+require "jsduck/tag/boolean_tag"
 
 module JsDuck::Tag
-  # Implementation of @new tag.
-  class New < JsDuck::MetaTag
+  class New < BooleanTag
     def initialize
-      @name = "new"
-      @key = :new
-      @signature = {:long => "&#9733;", :short => "&#9733;"} # unicode black star char
-      @boolean = true
+      @pattern = "new"
+      # A :tooltip field gets injected to this signature in Process::Versions
+      @signature = {:long => "&#9733;", :short => "&#9733;"}
+      # black (docs text color) unicode star on yellow background
+      @css = <<-EOCSS
+        .signature .new {
+          color: #484848;
+          background-color: #F5D833;
+        }
+      EOCSS
+      super
     end
-
-    # Initializes the tooltip text.
-    #
-    # HACK: This is a special method that's only called for the @new
-    # tag. It doesn't fit well into the current meta-tags system.  But
-    # until we rework the meta-tags system, this will have to do.
-    def create_tooltip!(imports, new_since)
-      if new_since
-        @signature[:tooltip] = "New since #{new_since}"
-      elsif imports.length > 0
-        @signature[:tooltip] = "New since #{imports.last[:version]}"
-      end
-    end
-
-    def to_value(contents)
-      true
-    end
-
   end
 end
-