jsduck 4.10.4 → 5.0.0.beta01

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)
+      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,87 @@
+require "jsduck/tag/tag"
+require "jsduck/doc/subproperties"
+require "jsduck/render/subproperties"
+require "jsduck/docs_code_comparer"
+require "jsduck/logger"
+
+module JsDuck::Tag
+  class Param < Tag
+    def initialize
+      @pattern = "param"
+      @tagname = :params
+      @merge_context = :method_like
+      @html_position = POS_PARAM
+    end
+
+    # @param {Type} [name=default] (optional) ...
+    def parse_doc(p)
+      tag = p.standard_tag({:tagname => :params, :type => true, :name => 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)
+    end
+
+    def merge(h, docs, code)
+      h[:params] = merge_params(docs, code, h[:files].first)
+    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
+
+    private
+
+    def merge_params(docs, code, file)
+      explicit = docs[:params] || []
+      implicit = JsDuck::DocsCodeComparer.matches?(docs, code) ? (code[:params] || []) : []
+      ex_len = explicit.length
+      im_len = implicit.length
+
+      if ex_len == 0 || im_len == 0
+        # Skip
+      elsif ex_len < im_len
+        # Warn when less parameters documented than found from code.
+        JsDuck::Logger.warn(:param_count, "Detected #{im_len} params, but only #{ex_len} documented.", file[:filename], file[:linenr])
+      elsif ex_len > im_len
+        # Warn when more parameters documented than found from code.
+        JsDuck::Logger.warn(:param_count, "Detected #{im_len} params, but #{ex_len} documented.", file[:filename], file[:linenr])
+      elsif implicit.map {|p| p[:name] } != explicit.map {|p| p[:name] }
+        # Warn when parameter names don't match up.
+        ex_names = explicit.map {|p| p[:name] }
+        im_names = implicit.map {|p| p[:name] }
+        str = ex_names.zip(im_names).map {|p| ex, im = p; ex == im ? ex : (ex||"")+"/"+(im||"") }.join(", ")
+        JsDuck::Logger.warn(:param_count, "Documented and auto-detected params don't match: #{str}", file[:filename], file[:linenr])
+      end
+
+      # Override implicit parameters with explicit ones
+      # But if explicit ones exist, don't append the implicit ones.
+      params = []
+      (ex_len > 0 ? ex_len : im_len).times do |i|
+        im = implicit[i] || {}
+        ex = explicit[i] || {}
+        params << {
+          :type => ex[:type] || im[:type] || "Object",
+          :name => ex[:name] || im[:name] || "",
+          :doc => ex[:doc] || im[:doc] || "",
+          :optional => ex[:optional] || false,
+          :default => ex[:default],
+          :properties => ex[:properties] || [],
+        }
+      end
+      params
+    end
+
+  end
+end

data/lib/jsduck/tag/preventable.rb

@@ -1,23 +1,33 @@
-require "jsduck/meta_tag"
+require "jsduck/tag/tag"
 
 module JsDuck::Tag
-  # Implementation of @preventable tag
-  class Preventable < JsDuck::MetaTag
+  # 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
-      @name = "preventable"
-      @key = :preventable
+      @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 to_value(contents)
-      true
+    def parse_doc(p)
+      p.match(/.*$/)
+      {:tagname => :preventable}
     end
 
-    def to_html(v)
+    def process_doc(h, docs, pos)
+      h[:preventable] = true
+    end
+
+    def to_html(context)
       <<-EOHTML
-        <div class='signature-box preventable'>
+        <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>
@@ -25,4 +35,3 @@ module JsDuck::Tag
     end
   end
 end
-

data/lib/jsduck/tag/private.rb

@@ -1,20 +1,35 @@
-require "jsduck/meta_tag"
+require "jsduck/tag/boolean_tag"
 
 module JsDuck::Tag
-  # Implementation of @private tag.
-  #
-  # Marks class/member as private.
-  #
-  # Because :private is accessed a lot internally, it's also injected
-  # to the main hash of documentation item.
-  #
-  class Private < JsDuck::MetaTag
+  class Private < BooleanTag
     def initialize
-      @name = "private"
-      @key = :private
-      @boolean = true
+      @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,39 @@
+require "jsduck/tag/tag"
+require "jsduck/doc/subproperties"
+
+module JsDuck::Tag
+  class Property < Tag
+    def initialize
+      @pattern = "property"
+      @tagname = :property
+      @member_type = {
+        :name => :property,
+        :category => :property_like,
+        :title => "Properties",
+        :position => MEMBER_POS_PROPERTY,
+        :subsections => [
+          {:title => "Instance properties", :filter => {:static => false}, :default => true},
+          {:title => "Static properties", :filter => {:static => true}},
+        ]
+      }
+    end
+
+    # @property {Type} [name=default] ...
+    def parse_doc(p)
+      tag = p.standard_tag({:tagname => :property, :type => true, :name => true})
+      tag[:doc] = :multiline
+      tag
+    end
+
+    def process_doc(h, tags, pos)
+      p = tags[0]
+      h[:name] = p[:name]
+      # Type might also come from @type, don't overwrite it with nil.
+      h[:type] = p[:type] if p[:type]
+      h[:default] = p[:default]
+      h[:properties] = JsDuck::Doc::Subproperties.nest(tags, pos)[0][:properties]
+      # Documentation after the first @property is part of the top-level docs.
+      h[:doc] += p[:doc]
+    end
+  end
+end

data/lib/jsduck/tag/protected.rb

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

data/lib/jsduck/tag/ptype.rb

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

data/lib/jsduck/tag/readonly.rb

@@ -1,14 +1,11 @@
-require "jsduck/meta_tag"
+require "jsduck/tag/boolean_tag"
 
 module JsDuck::Tag
-  # Implementation of @readonly tag
-  class Readonly < JsDuck::MetaTag
+  class Readonly < BooleanTag
     def initialize
-      @name = "readonly"
-      @key = :readonly
+      @pattern = "readonly"
       @signature = {:long => "readonly", :short => "R O"}
-      @boolean = true
+      super
     end
   end
 end
-

data/lib/jsduck/tag/removed.rb

@@ -1,36 +1,28 @@
-require "jsduck/meta_tag"
+require "jsduck/tag/deprecated_tag"
 
 module JsDuck::Tag
-  # Implementation of @removed 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 < JsDuck::MetaTag
+  # completely gone now.  Other than that it behaves exactly like
+  # @deprecated.
+  class Removed < DeprecatedTag
     def initialize
-      @name = "removed"
-      @key = :removed
-      @signature = {:long => "removed", :short => "REM"}
-      @multiline = true
-    end
-
-    def to_value(contents)
-      text = contents[0]
-      if text =~ /\A([0-9.]+)(.*)\Z/
-        {:version => $1, :text => $2.strip}
-      else
-        {:text => text || ""}
-      end
-    end
-
-    def to_html(val)
-      ver = val[:version] ? "since " + val[:version] : ""
-      <<-EOHTML
-        <div class='signature-box removed'>
-        <p>This #{@context[:tagname]} has been <strong>removed</strong> #{ver}</p>
-        #{format(val[:text])}
-        </div>
-      EOHTML
+      @tagname = :removed
+      # 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 strong {
+          color: #aa0000;
+          border: 1px solid #aa0000;
+          background-color: transparent;
+          text-decoration: line-through;
+        }
+      EOCSS
+      super
     end
   end
 end
-

data/lib/jsduck/tag/required.rb

@@ -1,4 +1,4 @@
-require "jsduck/meta_tag"
+require "jsduck/tag/tag"
 
 module JsDuck::Tag
   # There is no @required tag.
@@ -6,16 +6,18 @@ module JsDuck::Tag
   #
   #    @cfg {Type} someName (required)
   #
-  # This class is only used for displaying the required attribute, not
-  # for detecting it.  The detection is done with custom logic in
-  # DocParser and Merger classes.
-  class Required < JsDuck::MetaTag
+  # 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
-      @name = "--non-matching-requried-tag--"
-      @key = :required
+      @tagname = :required
       @signature = {:long => "required", :short => "REQ"}
-      @boolean = true
+      @css = ".signature .required { background-color: #484848 }" # Docs text color
+    end
+
+    def process_doc(h, docs, pos)
+      h[:required] = true
     end
   end
 end
-