solvas-jsduck 6.0.0.beta.1888

data/lib/jsduck/tag/new.rb

@@ -0,0 +1,32 @@
+require "jsduck/tag/boolean_tag"
+
+module JsDuck::Tag
+  class New < BooleanTag
+    def initialize
+      @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 based on the --new-since and
+    # --import options passed from command line.
+    #
+    # NOTE: This method is explicitly called from JsDuck::Options class.
+    def init_tooltip!(opts)
+      if opts.new_since
+        @signature[:tooltip] = "New since #{opts.new_since}"
+      elsif opts.import.length > 0
+        @signature[:tooltip] = "New since #{opts.import.last[:version]}"
+      end
+    end
+
+  end
+end

data/lib/jsduck/tag/override.rb

@@ -0,0 +1,37 @@
+require "jsduck/tag/tag"
+require "jsduck/js/utils"
+
+module JsDuck::Tag
+  class Override < Tag
+    def initialize
+      @pattern = "override"
+      @tagname = :override
+      @ext_define_pattern = "override"
+    end
+
+    # @override nameOfOverride
+    def parse_doc(p, pos)
+      if classname = p.ident_chain
+        {
+          :tagname => :override,
+          :override => classname,
+        }
+      else
+        # When @override not followed by class name, ignore the tag.
+        # That's because the current ext codebase has some methods
+        # tagged with @override to denote they override something.
+        # But that's not what @override is meant for in JSDuck.
+        nil
+      end
+    end
+
+    def process_doc(h, tags, pos)
+      h[:override] = tags[0][:override]
+    end
+
+    def parse_ext_define(cls, ast)
+      cls[:override] = JsDuck::Js::Utils.make_string(ast)
+    end
+
+  end
+end

data/lib/jsduck/tag/overrides.rb

@@ -0,0 +1,29 @@
+require "jsduck/tag/tag"
+
+module JsDuck::Tag
+  # There is no @overrides tag.  Though there is a separate @override
+  # tag, this class here has little to do with it.
+  #
+  # This here covers the HTML rendering of :overrides field, which
+  # gets added to members that override a member in their parent
+  # class.
+  class Overrides < Tag
+    def initialize
+      @tagname = :overrides
+      @html_position = POS_OVERRIDES
+    end
+
+    # Generate HTML links from :overrides data.
+    def format(m, formatter)
+      m[:overrides].each do |o|
+        label = o[:owner] + "." + o[:name]
+        o[:link] = formatter.link(o[:owner], o[:name], label, m[:tagname], m[:static])
+      end
+    end
+
+    def to_html(m)
+      "<p>Overrides: " + m[:overrides].map {|o| o[:link] }.join(", ") + "</p>"
+    end
+
+  end
+end

data/lib/jsduck/tag/param.rb

@@ -0,0 +1,46 @@
+require "jsduck/tag/tag"
+require "jsduck/doc/subproperties"
+require "jsduck/render/subproperties"
+
+module JsDuck::Tag
+  class Param < Tag
+    def initialize
+      @pattern = "param"
+      @tagname = :params
+      @repeatable = true
+      @html_position = POS_PARAM
+    end
+
+    # @param {Type} [name=default] (optional) ...
+    def parse_doc(p, pos)
+      tag = p.standard_tag({
+          :tagname => :params,
+          :type => true,
+          :name => true,
+          :default => true,
+          :optional => true
+        })
+      tag[:optional] = true if parse_optional(p)
+      tag[:doc] = :multiline
+      tag
+    end
+
+    def parse_optional(p)
+      p.hw.match(/\(optional\)/i)
+    end
+
+    def process_doc(h, tags, pos)
+      h[:params] = JsDuck::Doc::Subproperties.nest(tags, pos)
+      h[:params] = nil if h[:params].length == 0
+    end
+
+    def format(m, formatter)
+      m[:params].each {|p| formatter.format_subproperty(p) }
+    end
+
+    def to_html(m)
+      JsDuck::Render::Subproperties.render_params(m[:params]) if m[:params].length > 0
+    end
+
+  end
+end

data/lib/jsduck/tag/preventable.rb

@@ -0,0 +1,37 @@
+require "jsduck/tag/tag"
+
+module JsDuck::Tag
+  # That's pretty much a boolean tag, but we don't inherit from
+  # BooleanTag as unlike other boolean tags it can be followed by some
+  # text.
+  class Preventable < Tag
+    def initialize
+      @pattern = "preventable"
+      @tagname = :preventable
+      @signature = {:long => "preventable", :short => "PREV"}
+      @html_position = POS_PREVENTABLE
+      # Use the default white box with dark gray border.
+      @css = ".preventable-box { text-align: center }"
+    end
+
+    # @preventable is optionally followed by some method name, but we
+    # don't document it.
+    def parse_doc(p, pos)
+      p.match(/.*$/)
+      {:tagname => :preventable}
+    end
+
+    def process_doc(h, docs, pos)
+      h[:preventable] = true
+    end
+
+    def to_html(context)
+      <<-EOHTML
+        <div class='rounded-box preventable-box'>
+        <p>This action following this event is <b>preventable</b>.
+        When any of the listeners returns false, the action is cancelled.</p>
+        </div>
+      EOHTML
+    end
+  end
+end

data/lib/jsduck/tag/private.rb

@@ -0,0 +1,35 @@
+require "jsduck/tag/boolean_tag"
+
+module JsDuck::Tag
+  class Private < BooleanTag
+    def initialize
+      @pattern = "private"
+      @signature = {:long => "private", :short => "PRI"}
+      @html_position = POS_PRIVATE
+      @css = <<-EOCSS
+        .signature .private {
+          background-color: #FD6B1B; /* orange */
+        }
+        .private-box {
+          background-color: #fee;
+          text-align: center;
+          color: #600;
+          margin-bottom: 1em;
+        }
+      EOCSS
+      super
+    end
+
+    # Add notice to private classes
+    def to_html(context)
+      return unless context[:tagname] == :class
+
+      return [
+        "<div class='rounded-box private-box'>",
+        "<p><strong>NOTE:</strong> This is a private utility class for internal use ",
+        "by the framework. Don't rely on its existence.</p>",
+        "</div>",
+      ]
+    end
+  end
+end

data/lib/jsduck/tag/property.rb

@@ -0,0 +1,67 @@
+require "jsduck/tag/member_tag"
+require "jsduck/doc/subproperties"
+
+module JsDuck::Tag
+  class Property < MemberTag
+    def initialize
+      @pattern = "property"
+      @tagname = :property
+      @repeatable = true
+      @member_type = {
+        :title => "Properties",
+        :position => MEMBER_POS_PROPERTY,
+        :icon => File.dirname(__FILE__) + "/icons/property.png",
+        :subsections => [
+          {:title => "Instance properties", :filter => {:static => false}, :default => true},
+          {:title => "Static properties", :filter => {:static => true}},
+        ]
+      }
+    end
+
+    # @property {Type} [name=default] ...
+    def parse_doc(p, pos)
+      tag = p.standard_tag({
+          :tagname => :property,
+          :type => true,
+          :name => true,
+          :default => true,
+          :optional => true
+        })
+      tag[:doc] = :multiline
+      tag
+    end
+
+    def process_doc(h, tags, pos)
+      p = tags[0]
+      # Type might also come from @type, don't overwrite it with nil.
+      h[:type] = p[:type] if p[:type]
+      h[:default] = p[:default]
+
+      # Documentation after the first @property is part of the top-level docs.
+      h[:doc] += p[:doc]
+
+      nested = JsDuck::Doc::Subproperties.nest(tags, pos)[0]
+      h[:properties] = nested[:properties]
+      h[:name] = nested[:name]
+    end
+
+    def process_code(code)
+      h = super(code)
+      h[:type] = code[:type]
+      h[:default] = code[:default]
+      h[:readonly] = code[:readonly]
+      h
+    end
+
+    # Do the merging of :type field
+    def merge(h, docs, code)
+      if h[:type] == nil
+        h[:type] = code[:tagname] == :method ? "Function" : "Object"
+      end
+    end
+
+    def to_html(property, cls)
+      member_link(property) + " : " + property[:html_type]
+    end
+  end
+end

data/lib/jsduck/tag/protected.rb

@@ -0,0 +1,12 @@
+require "jsduck/tag/boolean_tag"
+
+module JsDuck::Tag
+  class Protected < BooleanTag
+    def initialize
+      @pattern = "protected"
+      @signature = {:long => "protected", :short => "PRO"}
+      @css = ".signature .protected { background-color: #9B86FC }" # Violet
+      super
+    end
+  end
+end

data/lib/jsduck/tag/ptype.rb

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

data/lib/jsduck/tag/readonly.rb

@@ -0,0 +1,11 @@
+require "jsduck/tag/boolean_tag"
+
+module JsDuck::Tag
+  class Readonly < BooleanTag
+    def initialize
+      @pattern = "readonly"
+      @signature = {:long => "readonly", :short => "R O"}
+      super
+    end
+  end
+end

data/lib/jsduck/tag/removed.rb

@@ -0,0 +1,32 @@
+require "jsduck/tag/deprecated_tag"
+
+module JsDuck::Tag
+  # To document members that were present in previous version but are
+  # completely gone now.  Other than that it behaves exactly like
+  # @deprecated.
+  class Removed < DeprecatedTag
+    def initialize
+      @tagname = :removed
+      @msg = "This {TAGNAME} has been <strong>removed</strong>"
+      # striked-through text with red border.
+      @css = <<-EOCSS
+        .signature .removed {
+          color: #aa0000;
+          background-color: transparent;
+          border: 1px solid #aa0000;
+          text-decoration: line-through;
+        }
+        .removed-box {
+          border: 2px solid #aa0000;
+        }
+        .removed-box strong {
+          color: #aa0000;
+          border: 2px solid #aa0000;
+          background-color: transparent;
+          text-decoration: line-through;
+        }
+      EOCSS
+      super
+    end
+  end
+end

data/lib/jsduck/tag/required.rb

@@ -0,0 +1,23 @@
+require "jsduck/tag/tag"
+
+module JsDuck::Tag
+  # There is no @required tag.
+  # Instead the :required attribute is detected after @cfg:
+  #
+  #    @cfg {Type} someName (required)
+  #
+  # This class is only used for rendering the required attribute in
+  # HTML documentation, not for detecting it.  The detection is done
+  # with custom logic in @cfg and DocAst classes.
+  class Required < Tag
+    def initialize
+      @tagname = :required
+      @signature = {:long => "required", :short => "REQ"}
+      @css = ".signature .required { background-color: #484848 }" # Docs text color
+    end
+
+    def process_doc(h, docs, pos)
+      h[:required] = true
+    end
+  end
+end

data/lib/jsduck/tag/requires.rb

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

data/lib/jsduck/tag/return.rb

@@ -0,0 +1,48 @@
+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
+      @repeatable = true
+      @html_position = POS_RETURN
+    end
+
+    # @return {Type} return.name ...
+    def parse_doc(p, pos)
+      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